easy_svg_pro_registered_icon

Filter · Easy SVG Pro · Status: Stable

WordPress 7.1 has its own icon registry, and the core Icon block draws whatever that registry holds. Easy SVG Pro hands every icon of its collections to that registry. This filter sees each icon just before it is handed over, so you can change the markup the Icon block will show, for example add a class.

Usage

apply_filters( 'easy_svg_pro_registered_icon', string $content, string $reference )

Applied in includes/core/collections.php, inside registered_icon_content(), while the collections are registered with core on init at priority 11.

When to use it

• You want every icon of one collection to carry a class in the Icon block, so your theme's CSS can size or color them.
• You need to swap the drawing of one icon only in the Icon block, for example a simplified version that survives core's filtering.
• You want to log or count what reaches the registry while you debug an icon that shows up empty in the block.

Do not use it when:

• You want to change what easy_svg_icon(), Twig or the shortcode print. Those read the collection markup directly and never see this filter. Use the free plugin's easy_svg_icon_markup filter for that.
• The icon belongs to the free plugin's own library (easy-svg/...). That library goes through the free plugin's easy_svg_registrable_icons filter instead.
• You want sizes and colors managed by editors. Styles & theme colors under Icons → Features already uses this filter for that.

Parameters

Return value

Default

The output of easy_svg_core_icon() for the icon, or the stored markup when the free plugin does not provide that function.

Examples

A class on every icon of one collection

/**
 * Add "acme-icon" to the root svg of every acme/* icon in the Icon block.
 * Merges into an existing class attribute instead of adding a second one.
 */
function acme_registered_icon_class( $content, $reference ) {
	if ( 0 !== strpos( $reference, 'acme/' ) ) {
		return $content;
	}

	if ( preg_match( '/<svg\b[^>]*\bclass="/i', $content ) ) {
		return (string) preg_replace( '/(<svg\b[^>]*\bclass=")/i', '$1acme-icon ', $content, 1 );
	}

	return (string) preg_replace( '/<svg\b/i', '<svg class="acme-icon"', $content, 1 );
}
add_filter( 'easy_svg_pro_registered_icon', 'acme_registered_icon_class', 20, 2 );

Priority 20 runs after Styles & theme colors, which hooks in at 10, so its classes are already there when you merge yours.

A per-client class from a map

/**
 * Agency setup: each client collection gets the class its theme expects.
 */
function acme_client_icon_classes( $content, $reference ) {
	$classes = array(
		'client-north' => 'north-icon',
		'client-south' => 'south-icon',
	);

	$collection = strtok( $reference, '/' );

	if ( ! isset( $classes[ $collection ] ) || false !== strpos( $content, $classes[ $collection ] ) ) {
		return $content;
	}

	return (string) preg_replace( '/<svg\b/i', '<svg class="' . esc_attr( $classes[ $collection ] ) . '"', $content, 1 );
}
add_filter( 'easy_svg_pro_registered_icon', 'acme_client_icon_classes', 20, 2 );

This version assumes the root has no class yet. If you also run Styles & theme colors or have stroked icons, use the merging version above.

Find out what reaches the Icon block

/**
 * While debugging: log the registry content of one icon. Never ship this.
 */
function acme_debug_registered_icon( $content, $reference ) {
	if ( defined( 'WP_DEBUG_LOG' ) && WP_DEBUG_LOG && 'acme/phone' === $reference ) {
		error_log( 'Registry content for acme/phone: ' . $content );
	}

	return $content;
}
add_filter( 'easy_svg_pro_registered_icon', 'acme_debug_registered_icon', 99, 2 );

If the logged markup holds a circle, g or stroke, core will drop it. That is why an icon can look empty in the block while it renders fine through easy_svg_icon().

How it works

The filter only runs when all of these hold:

• the licence is active and Multiple collections is on under Icons → Features,
• WordPress has wp_register_icon() and wp_register_icon_collection(), which means WordPress 7.1 or newer.

Then, on every request on init at priority 11, after the sources (priority 9) and the free library (priority 10):

1. Every collection in the registry is registered with core: folder sources, the theme, code registrations and published icon sets.
2. For each icon, the markup goes through easy_svg_core_icon() from the free plugin, then through this filter, then to wp_register_icon() with the label from the manifest or the slug as words.
3. Core runs wp_kses over the content with its own allow-list and keeps only that.

What core keeps (measured on WordPress 7.1.3, there is no filter for it):

Everything else, including circle, rect, g, style and every stroke attribute, is dropped. This is why the free plugin rewrites shapes as paths and turns strokes into classes before your filter runs.

The filter runs once per icon per request. A site with 2000 icons calls it 2000 times on every page load, so keep your callback cheap.

Pitfalls

• Core gets the last word. Anything outside the allow-list you add is silently removed by core. A style attribute, a stroke or a data- attribute never reaches the block. Use classes and CSS.
• Only the Icon block sees it. easy_svg_icon(), Twig, the shortcode and the pickers read the collection markup directly. Changing a drawing here makes the block and the template show different icons.
• One class attribute only. The root may already carry classes from the stroke rewrite or from Styles & theme colors. Adding a second class="" produces invalid markup and one of the two is lost. Merge into the existing attribute.
• Not for the free library. Icons addressed easy-svg/... come from the free plugin and go through easy_svg_registrable_icons.
• Nothing happens before WordPress 7.1. Without the core Icon API the filter never runs. Templates still render the icons through easy_svg_icon().

Related

• easy_svg_pro_collection_icons
• easy_svg_register_icon_collection()
• Tutorial: Ship icons from a theme or plugin