easy_svg_registrable_icons

Filter · Easy SVG · Status: Stable

easy_svg_registrable_icons gives you the whole icon library right before Easy SVG registers it with WordPress (version 7.1 or newer). Whatever you return is what the core Icon block offers and what wp_get_icon( 'easy-svg/...' ) prints. It is the only place to change that markup, because WordPress's icon registry offers no filter of its own.

Usage

add_filter( 'easy_svg_registrable_icons', 'myplugin_registrable_icons' );

function myplugin_registrable_icons( array $icons ): array {
	return $icons;
}

When to use it

• Hide icons from the editor's icon picker, for example drafts, logos for internal use, or icons a client should not pick.
• Recolour or resize icons for the Icon block before WordPress stores them.
• Add icons to the easy-svg collection from code (a theme folder, a build step) without storing them in the library.
• Rename what the picker shows, without touching the stored title.

When not to use it:

• For templates that call easy_svg_icon() or use the shortcode. They read the stored icon directly; use easy_svg_icon_markup there.
• To register a separate collection. Every entry goes into easy-svg; call wp_register_icon_collection() and wp_register_icon() yourself for a collection of your own.

Parameters

Return value

Default

The output of easy_svg_stored_icons(): every icon in the library.

Examples

Hide icons from the picker

Icons whose slug starts with internal- stay in the library and keep working in templates, but editors cannot pick them in the Icon block.

add_filter( 'easy_svg_registrable_icons', 'myplugin_hide_internal_icons' );

function myplugin_hide_internal_icons( $icons ) {
	return array_values(
		array_filter(
			(array) $icons,
			static function ( $icon ) {
				return 0 !== strpos( (string) ( $icon['slug'] ?? '' ), 'internal-' );
			}
		)
	);
}

Make every icon follow the text colour

Core's own stylesheet already sets fill: currentColor on the Icon block's SVG, but a fill written on a path wins. Removing hard-coded path fills lets the block's colour setting reach the icon.

add_filter( 'easy_svg_registrable_icons', 'myplugin_icons_follow_text_colour' );

function myplugin_icons_follow_text_colour( $icons ) {
	foreach ( (array) $icons as $i => $icon ) {
		if ( empty( $icon['content'] ) ) {
			continue;
		}
		$icons[ $i ]['content'] = preg_replace(
			'/\sfill="(?!none")[^"]*"/i',
			'',
			(string) $icon['content']
		);
	}
	return $icons;
}

fill="none" is kept on purpose: an outline icon needs it, and Easy SVG turns it into its stroke classes (see How it works).

Add icons from a theme folder

add_filter( 'easy_svg_registrable_icons', 'mytheme_add_theme_icons' );

function mytheme_add_theme_icons( $icons ) {
	$sanitizer = function_exists( 'easy_svg_sanitizer' ) ? easy_svg_sanitizer() : null;
	if ( null === $sanitizer ) {
		return $icons;
	}

	foreach ( glob( get_theme_file_path( 'icons/*.svg' ) ) ?: array() as $file ) {
		$slug  = sanitize_title( basename( $file, '.svg' ) );
		$clean = $sanitizer->sanitize( (string) file_get_contents( $file ) );
		if ( '' === $slug || ! is_string( $clean ) ) {
			continue;
		}
		$icons[] = array(
			'slug'    => 'theme-' . $slug,
			'label'   => ucwords( str_replace( '-', ' ', $slug ) ),
			'content' => $clean,
		);
	}

	return $icons;
}

This runs on every request. On a site with many files, cache the list (for example in a transient keyed by the theme version). Two entries with the same slug collide in core, and the first one registered wins.

Defensive: check the contract version

The filter is part of the icon contract since EASY_SVG_ICONS_API 1. A filter cannot be detected, so test the constant.

add_action( 'plugins_loaded', 'myplugin_register_icon_filters' );

function myplugin_register_icon_filters() {
	if ( ! defined( 'EASY_SVG_ICONS_API' ) ) {
		return; // Easy SVG missing, or older than 5.4.0.
	}
	add_filter( 'easy_svg_registrable_icons', 'myplugin_hide_internal_icons' );
}

How it works

The filter runs in easy_svg_boot_icons(), hooked on init at priority 10, after WordPress registered its own collections at priority 0. That hook is only added while the icon library is switched on under Icons, Settings, and the function returns early on WordPress without wp_register_icon() and wp_register_icon_collection() (before 7.1).

Details that matter for your callback:

• Caching. The list you receive comes from the transient easy_svg_icons (one day), tied to the option easy_svg_icons_version that every icon change raises. Your filter is not cached: it runs on every request, so a code change applies immediately.
• After your filter, each entry's content goes through easy_svg_core_icon(): circles, rectangles, ellipses, lines and polylines become paths, groups are flattened onto their children, and an icon drawn only with strokes gets the classes esvg-stroke, esvg-sw-*, esvg-cap-round and esvg-join-round. A small inline stylesheet (fill: none; stroke: currentColor) restores the stroke wherever core prints the icon. If your markup is not valid XML, this rewrite is skipped and your markup is passed on unchanged.
• Then core runs wp_kses with its own allow-list: svg (with class, xmlns, width, height, viewBox, aria-hidden, role, focusable), path and polygon (with fill, fill-rule, d or points, transform). Everything else is dropped, including title, gradients, masks, use, text and stroke attributes.
• Supported stroke widths for the class mapping are 1, 1.25, 1.5, 1.75, 2, 2.5 and 3. Another width falls back to 1.

Pitfalls

• Registering the filter too late. Add it in a plugin file or functions.php, not inside an init callback with a priority above 10.
• Losing the list. Return the array on every path. Returning nothing removes every icon from the Icon block (saved blocks then show a notice in the editor that their icon is missing).
• Valid names only. A slug with capitals, spaces or a slash is skipped silently. Use sanitize_title() and check against EASY_SVG_ICON_NAME_PATTERN.
• No effect on templates. easy_svg_icon() and the shortcode ignore this filter.
• Unsupported drawing. Anything outside paths and polygons (text, gradients, masks, use) cannot survive core's allow-list.
• Removing an icon breaks saved blocks. A block saved with easy-svg/old-logo draws nothing once that entry is gone.

Related

• easy_svg_icon_markup
• easy-svg
• easy_svg_boot_icons()
• easy_svg_stored_icons()
• easy_svg_core_icon()
• EASY_SVG_ICONS_API
• EASY_SVG_STROKE_WIDTHS