easy-svg

Block · Easy SVG · Status: Stable

Easy SVG does not ship a block of its own. Instead it adds your icon library to the core Icon block as a collection called "Easy SVG" (slug easy-svg). Editors pick your icons in the block's icon picker, and themes can print them with WordPress's own wp_get_icon(). This needs WordPress 7.1 or newer, which introduced the icon registry.

Usage

// What the plugin does on init, priority 10:
wp_register_icon_collection( 'easy-svg', array( 'label' => 'Easy SVG' ) );
wp_register_icon( 'easy-svg/heart', array( 'label' => 'Heart', 'content' => '...' ) );

In block content an icon from the collection is saved as:

<!-- wp:icon {"icon":"easy-svg/heart"} /-->

When to use it

• Editors should place icons visually in the block editor or the site editor, with the block's own colour and size controls.
• A block theme or pattern needs icons: write the block markup above into the pattern.
• A PHP template on 7.1 or newer wants the same drawing the block shows: wp_get_icon( 'easy-svg/heart' ).

When not to use it:

• On WordPress older than 7.1: there is no Icon block. Use easy_svg_icon() or the [easy_svg_icon] shortcode.
• For icons that need gradients, masks, text or use references: the registry keeps only paths and polygons. Render those with easy_svg_icon(), which prints the stored file.

Parameters

The collection itself takes no parameters you can change. Each icon in it is addressed as easy-svg/ plus the icon's slug, for example easy-svg/arrow-left. The slug must match EASY_SVG_ICON_NAME_PATTERN (lowercase letters, digits, - and _, starting and ending with a letter or digit); the library only creates such slugs.

For wp_get_icon() (a WordPress core function, not part of Easy SVG):

Return value

Default

Registered only when all of these hold: WordPress has wp_register_icon() and wp_register_icon_collection() (7.1 or newer), the icon library is switched on under Icons, Settings, and at least one icon has a usable slug. Its label is "Easy SVG", translated with the plugin's text domain.

Examples

Print the block's drawing from a template

if ( function_exists( 'wp_get_icon' ) ) {
	echo wp_get_icon( // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped
		'easy-svg/heart',
		array(
			'size'  => 20,
			'class' => 'card__icon',
			'label' => __( 'Favourite', 'mytheme' ),
		)
	);
}

Icon block in a pattern

<!-- wp:group {"layout":{"type":"flex"}} -->
<div class="wp-block-group">
	<!-- wp:icon {"icon":"easy-svg/phone"} /-->
	<!-- wp:paragraph --><p>030 1234567</p><!-- /wp:paragraph -->
</div>
<!-- /wp:group -->

Fall back on older WordPress

function mytheme_icon( $slug, $label = '' ) {
	if ( function_exists( 'wp_get_icon' ) ) {
		$svg = wp_get_icon( 'easy-svg/' . $slug, array( 'label' => $label ) );
		if ( '' !== $svg ) {
			return $svg;
		}
	}
	if ( function_exists( 'easy_svg_icon' ) ) {
		return easy_svg_icon( $slug, array( 'label' => $label ) );
	}
	return '';
}

The two paths can look different for icons that use shapes or strokes, because the block's version was rewritten for the registry (see How it works).

Check that the collection is there

Run this after init priority 10, for example in a template or on wp_loaded.

$has_collection = class_exists( 'WP_Icon_Collections_Registry' )
	&& WP_Icon_Collections_Registry::get_instance()->is_registered( 'easy-svg' );

false means WordPress is older than 7.1, the icon library is switched off, or the library holds no usable icon yet.

How it works

1. When. On init at priority 10, after WordPress registered its own core collection at priority 0. Not limited to the admin: the Icon block is rendered on the server, so the icons have to exist for visitors too.
2. What. Every stored icon, oldest first, read in pages of 100 and cached for a day. The cache is dropped whenever an icon is added, replaced, renamed or deleted.
3. Rewrite for the registry. WordPress runs wp_kses over every icon with a fixed allow-list: svg, path and polygon, and on paths only fill, fill-rule, d and transform. To keep icons visible, Easy SVG first rewrites each drawing: circles, rectangles (with rounded corners), ellipses, lines and polylines become paths, groups are flattened onto their children (their transform and fill travel along), and an outline icon gets the classes esvg-stroke, esvg-sw-* (stroke widths 1, 1.25, 1.5, 1.75, 2, 2.5, 3), esvg-cap-round and esvg-join-round.
4. Stroke stylesheet. When at least one registered icon carries those classes, a small inline stylesheet (easy-svg-stroke-icons) is printed on the front end and in the editor. It sets fill: none; stroke: currentColor on the paths, so outline icons take the text colour of the block.
5. Missing icons. In the editor, an Icon block whose icon is no longer registered shows a notice. The front end stays silent and the block draws nothing.

Caching: there is nothing to clear by hand. The icon list lives in the transient easy_svg_icons together with the version number from the option easy_svg_icons_version; any write through the plugin raises the version.

Pitfalls

• Colours. A fixed stroke colour becomes currentColor. A mixed icon (some parts filled, some stroked) keeps its fills but loses its strokes, because one class cannot express both.
• What is lost. Gradients, masks, clip paths, use, text, title and per-element opacity cannot pass core's allow-list. Such parts disappear in the block, while easy_svg_icon() still shows them.
• Library switch. Switching the icon library off removes the collection from the next request on. Saved blocks keep their reference and draw nothing until it is switched on again.
• Deleting an icon. Saved blocks that use it draw nothing. Rename instead of deleting and re-adding, because renaming keeps the slug.
• The library's copy button. It still offers the block form only for icons drawn with paths and polygons, even though the plugin now converts simple shapes for the block.
• Not a template filter. Changes made with easy_svg_icon_markup do not reach the block; use easy_svg_registrable_icons.

Related

• easy_svg_registrable_icons
• easy_svg_icon()
• easy_svg_register_icons()
• easy_svg_core_icon()
• easy_svg_icons_supported()
• EASY_SVG_ICON_COLLECTION
• Render icons in themes