Register a Custom Source

Register a file-based source when a plugin or theme needs to make its own SVG collection available in the Jooosi Icon picker, collection list, and search results.

Prepare the icon directory#

Put SVG files directly in one directory; Jooosi Icon uses each file name, without the .svg extension, as the icon name. For example, icons/shopping-cart.svg in a source with the acme prefix is referenced as acme:shopping-cart. The source scanner looks for SVG files at the top level of the configured directory.

Choose a unique prefix made of lowercase letters, numbers, and hyphens. The prefixes local and omni are reserved.

Register the source#

Add the filter from your plugin or theme’s PHP code. Replace the example name, directory, and prefix with your own values. This example leaves the optional public URL unset; if you add one, make sure it matches the public URL for the path directory:

add_filter('jooosi-icon/service/icon:sources', static function (array $sources): array {
    $icon_dir = __DIR__ . '/icons';

    $sources['acme'] = [
        'name' => 'Acme Icons',
        'path' => $icon_dir,
        ];

    return $sources;
});

• name is the source label shown to people.
• path is the server filesystem path to the directory of SVG files.
• url is optional. Set it to the public base URL when the icons should have a public URL in their metadata.

Use a unique prefix as the array key (in the example, acme). Keep your SVG files directly inside the directory named by path; the scanner does not look through nested folders.

Register the filter before first use#

Jooosi Icon resolves file-based sources lazily, when the icon registry, collection list, or search is used for the first time. Add the filter during normal plugin or theme setup, before any icon is requested, so the source is present on that first lookup.

After registration, open the icon picker and search for an icon using prefix:name, such as acme:shopping-cart. The source is also included in the collections and search API.

Troubleshooting#

• Check that path points to an existing, readable directory and that the SVG files are directly inside it.
• Check that the prefix uses lowercase letters, numbers, or hyphens, and is not local or omni.
• Check that the filter runs before the first icon lookup and that the file name matches the name entered in the picker.

For custom uploads managed in WordPress, see Local SVG Icons. For the web component and REST API, see Developer Reference.