easy_svg_pro_theme_collection_slug

Choose the collection slug the active theme's assets/icons folder registers under, so templates call your theme's icons as acme/phone instead of theme/phone.

Filter · Easy SVG Pro · Status: Stable

The active theme's assets/icons folder is read as one icon collection. Its slug is the first half of every icon address, as in theme/phone. This filter lets you choose that slug, for example the client's brand name.

Usage

apply_filters( 'easy_svg_pro_theme_collection_slug', string $slug )

Applied in includes/sources/sources.php, inside boot_sources() on init at priority 9.

When to use it

You build a theme for a client and want the icons addressed as acme/phone, which reads better in templates and cannot be confused with another theme's icons.
You switch a site to a new theme and want the old addresses to keep working: return the slug the previous theme used.
Your theme cannot ship a manifest.json with a slug (for example a parent theme you do not control), but a child theme or plugin can add this filter.

Do not use it when:

Your theme can carry a manifest.json in assets/icons. A "slug" there does the same without code, and this filter still receives it as its default.
Your icons are not in assets/icons. Register that folder with easy_svg_register_icon_collection() instead.

Parameters

body

$slugstring

Required

The slug the theme collection would register under: the slug from the child theme's assets/icons/manifest.json, else the parent theme's, else theme.

Return value

returnstring

The collection slug to use. It is cast to a string and not validated. Return lowercase letters, digits, hyphens and underscores only, starting and ending with a letter or digit, and never an empty string.

Default

'theme', or the slug from the theme folder's manifest.json (child before parent).

Examples

A fixed brand slug

/**
 * Address this theme's icons as acme/icon-name.
 */
function acme_theme_icon_slug( $slug ) {
	return 'acme';
}
add_filter( 'easy_svg_pro_theme_collection_slug', 'acme_theme_icon_slug' );

Keep a manifest slug, fall back to the theme's folder name

/**
 * Use the manifest's slug when there is one, else the stylesheet folder name.
 */
function acme_theme_icon_slug_from_folder( $slug ) {
	if ( 'theme' !== $slug ) {
		return $slug;
	}

	$folder = sanitize_key( get_stylesheet() );

	return '' !== $folder ? $folder : $slug;
}
add_filter( 'easy_svg_pro_theme_collection_slug', 'acme_theme_icon_slug_from_folder' );

sanitize_key() can leave an underscore at the start or end. If your theme folder names allow that, trim them with trim( $folder, '_-' ).

Keep old addresses alive after a theme switch

/**
 * The site used to run "Agency Classic", whose icons were called agency/*.
 * The new theme ships the same file names, so keep that slug.
 */
function acme_keep_legacy_icon_slug( $slug ) {
	return 'agency';
}
add_filter( 'easy_svg_pro_theme_collection_slug', 'acme_keep_legacy_icon_slug' );

Defensive: only accept a valid slug

function acme_safe_theme_icon_slug( $slug ) {
	$wanted = defined( 'ACME_ICON_SLUG' ) ? (string) ACME_ICON_SLUG : '';

	if ( 1 === preg_match( '/^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?$/', $wanted ) ) {
		return $wanted;
	}

	return $slug;
}
add_filter( 'easy_svg_pro_theme_collection_slug', 'acme_safe_theme_icon_slug' );

The pattern is the one Easy SVG uses for icon and collection names.

How it works

This runs only while the licence is active, Theme & folder sources is on under Icons → Features, and the free plugin can sanitize and harden. Then, on every request:

assets/icons of the parent theme and of the active (child) theme are scanned. If they are the same folder, it is read once.
The two are merged into one collection. An icon in the child theme replaces the parent's icon of the same name. The child's manifest slug and label win over the parent's.
The default slug is the manifest slug, else theme, and the label is the manifest label, else "Theme icons".
This filter is applied to the slug. It runs even when the theme has no icon folder at all.
The collection is registered under the slug you returned, and the screens record it as coming from the theme, including whether a child theme overrides parent icons.

Drop-in folders under wp-content/easy-svg-icons are registered after the theme. If one of them wants the same slug, the drop-in is the one that moves aside (for example to acme-2).

The slug is not stored anywhere. It is decided again on every request, so a changed filter takes effect on the next page load.

Pitfalls

Renaming breaks every address. Blocks, custom fields, Twig templates and PHP calls store the full address theme/phone. Change the slug on a live site and all of them render nothing. Decide the slug before content is created, or keep the old one.
Nothing checks your return value. An uppercase slug, a space or an empty string is used as it stands. WordPress's Icon API may then refuse the collection, and icon addresses stop matching. Return a clean lowercase slug.
Two collections, one slug. Returning the slug of an existing icon set or a code registration merges both into one collection: icons are added by name, and the label of whichever registers last wins.
It is not a label. The name shown in the inserter comes from the manifest label, else "Theme icons". This filter only changes the slug.
Switching themes changes the default. A new theme without a manifest falls back to theme, a new theme with a different manifest slug changes every address. Keep the filter in a plugin if the addresses must survive a theme switch.

Was this page helpful?