SVG Icon API: Iteration for WordPress 7.1

[t-hamano]

• Core ticket: https://core.trac.wordpress.org/ticket/64847
• Important Issues and PRs:
  • Add an Icons block #16484
  • SVG Icon registration API  #72215
  • New Block: Icon Block #71227

---

We have stabilized three core features and shipped them in 7.0 Beta1:

• WP_Icons_Registry class: The singleton class that loads core SVG icons from a manifest file, stores them, and exposes methods to check registration and retrieve icon data and content. There is currently no way to register a custom icon.
• WP_REST_Icons_Controller: The REST API controller that exposes the icon registry over wp/v2/icons, letting the editor list icons and fetch a single icon by name.
• Icon block (core/icon): The core block that retrieves a list of icons from the endpoint and lists them in a modal. The selected icon name is saved as an attribute, and the content is rendered server-side via the icon registry.

To make the Icon API more robust and extensible, I believe the following features are necessary:

Code quality

• Use snake_case "file_path" key: Icons: Use snake_case file_path key in icon registry #79100
• SVG sanitization (ref): There is no core function to properly sanitize SVGs, so a class method currently does the job, but it is not perfect, and there is room for improvement. See #75550 for more details. Maybe we could create a core function like sanitize_svg() instead.
  Icons Registry: improve SVG sanitizer #75550

✅ Icon registry enhancements

• Icon namespace validation (ref): Currently, custom icon registration is not allowed, and the namespace is hardcoded as core/. If we allow custom icon registration in the future, we will need to strictly check that the icon name follows the {namespace/icon-name} format.
  Icons: Enforce strict name validation in register method #76079

✅ REST API enhancements

• Search based on keywords: The current endpoint allows us to filter icons by the search parameter, but only the name field is referenced. We could also reference the label field and an optional keywords field. Icons API: Support searching in labels; extend classes post-7.0 work #75878
• Create public APIs (ref): I think we need APIs like the one below to allow consumers to filter the core icons and submit custom icons.
  • register_icon() function
  • unregister_icon() function
  • core-icons theme support: This is similar to the core-block-patterns theme support: if this support is disabled, all core icons will not be registered.
  • Icons: Add APIs for collection and icon registration #77260
  • Icons: Add PHP method(s) for rendering inline SVG icons from the registry #78332

✅ Collection Support

Similar to Font Library, it should be possible to support collection: consumers will want to group icon sets based on their own brand.

• Create a registry like WP_Icon_Colloections_Registry
• Create an endpoint like WP_REST_Icons_Colloections_Controller
• Create public APIs:
  • wp_register_icon_collection() function
  • wp_unregister_icon_collection() function
  • _wp_register_default_icon_collections function
• Icons: Add APIs for collection and icon registration #77260
• Icons: Filter the icon library picker by collection #79681

Create Icon Picker Modal component

• To avoid increasing bundle size, the initial implementation built a custom picker without using DataViewPicker. (ref) Perhaps it should be possible to add a component like IconPickerModal to the @wordpress/block-editor package and load it from a block. This icon picker should be useful for blocks other than the Icon block as well.
  • DataViewsPicker based UI
  • Filter icons by category
  • Icons: Move IconPickerModal into block-editor for reusability #76787

Icon block enhancements

For example, the early prototype of the Icon Block had the following features, which we can consider as enhancements:

• Flip and rotate icon
  Icon Block: Add flip and rotate transformation controls #77017
• Should we allow icons to have links?
  Add link support to the Icon block #79057

Customizable icon support for other blocks

Some icons render their own hard-coded SVG content or symbols. Make those icons selectable via the Icon API.

• Navigation block: Toggle button, Overlay Close button
  • Add more collapsed navigation icon options #61755
• Breadcrumbs: Separator (The text can be changed, but the icon cannot be used)
  • [WIP] Add icon support for Breadcrumbs separator in block editor #77059
• Navigation Overly Close block: Close icon
• Accordion Heading lock: Toggle icon (+ symbol)
  • Accordion Block: Block uses + sign rather than SVG for icon #73214
• Details block: Browser default triangle symbol
  • Details Block: allow the option to choose from a set of icons #51019

Inline SVG icon (Inline format)

• At the moment I don't know how to implement this. Perhaps it will be based on "BITS". (ref)
  • Add link support to the Icon block #79057 (comment)

[t-hamano]

@ryanwelcher @mcsf @tyxla @fabiankaegy, If there's anything I've missed or got wrong, feel free to update the task.

[Mamaduka]

Some ideas for performance improvements for the Icons API and block; I think these can go in WP 7.0.

• Icon Block: Fetch only selected icon, fetch collection on demand. Currently, this is the largest request on the page when an icon block is present. See the screenshot.
• REST Controller: Fix collection params schema and support the same arguments in the getIcons selector. The schema states the default per_page arg is 10, but it returns all the results. You can check defaults via https://example.test/wp-json/wp/v2/icons?_method=OPTIONS.

Screenshot

[hiroshisatoy]

Rather than suggesting ideas for areas where icons are already being used, I would like to propose an additional feature for blocks.

I would like the Button block to support setting an icon.
If implemented, I believe this would become a representative and practical use case for the icon registry.

Specifically, I would like:

• The ability to select an icon that appears before the Button block content
• The ability to select an icon that appears after the Button block content

For icon selection, please use the newly added Icon Picker Modal component.

The repository created by @ndiego —
https://github.com/ndiego/enable-button-icons
is extremely helpful and very close to what I have in mind. Please check the behavior in the Playground linked in the README.

Additionally, I have some feedback regarding the icon and the icon picker:

It would be beneficial to support something like keywords, separate from categories.
For example, a chevron-shaped icon (such as "<") should also appear when searching for a keyword like "arrow."

If keyword functionality has already been implemented or is currently under consideration, please disregard this suggestion.

[alexandrebuffet]

Hi, thanks for this work on the new Icon API, it's great to see this moving forward! 🙂

I've been following the discussions for a while, and here are a couple of ideas that might be worth considering:

1. Icon Collections
   @t-hamano mentions Category support, I'd suggest also introducing collections, aligned with the Font Collections concept already in core. In the Font Library, a collection is one "source" (e.g. Google Fonts) containing many font families, with categories (Sans Serif, Display, etc.) as semantic grouping. For icons, the same split would work:

• Collection: one icon set/source (e.g. "WordPress Icons", "Heroicons", "Theme Icons").
• Category: semantic grouping (e.g. "Arrows", "Social", "UI") that can span collections.

2. Icon Library
   Core already has a Font Library with a dedicated UI. I'd find it valuable to eventually have an Icon Library in the same spirit: a dedicated place to browse and manage icon sets (core, theme, plugins, and maybe user-uploaded later).

[fabiankaegy]

Thanks for creating this list :)

In regards to the icon picker and performance improvements. The Icon Picker we've built at 10up years ago has done quite a bit of that work already: https://github.com/10up/block-components/tree/develop/components/icon-picker With icons we encountered large icon systems like all of googles material icons library which then meant we had to look at react virtualization libraries etc to make the scrolling etc performant :) Happy for any of that work to help in moving the core implementation here forward. All the code is fully open source 👍

[t-hamano]

Thanks everyone for the feedback!

Some ideas for performance improvements for the Icons API and block; I think these can go in WP 7.0.

I'll try to fix this during the 7.0 release cycle.

• The ability to select an icon that appears before the Button block content
• The ability to select an icon that appears after the Button block content

This will be part of our implementation of inline SVG icons, which should allow us to insert icons anywhere in any block that supports RichText.

It would be beneficial to support something like keywords, separate from categories.
For example, a chevron-shaped icon (such as "<") should also appear when searching for a keyword like "arrow."

Just as blocks support keyword search, let's implement this for icons as well.

• Collection: one icon set/source (e.g. "WordPress Icons", "Heroicons", "Theme Icons").
• Category: semantic grouping (e.g. "Arrows", "Social", "UI") that can span collections.

I initially planned to only support categories, but this is a very good idea. The code might look like this:

register_icon_collection(
	'my-icons',
	array(
		'label'      => __( 'My Icons', 'my-plugin' ),
		'categories' => array(
			array(
				'slug'  => 'arrows',
				'title' => __( 'Arrows', 'my-plugin' ),
			),
			array(
				'slug'  => 'Social',
				'title' => __( 'Social', 'my-plugin' ),
			),
		),
	)
);

register_icon(
	'my-plugin/arrow-up',
	array(
		'label'    => __( 'Arrow Up', 'my-plugin' ),
		'filePath' => __DIR__ . '/arrow-up.svg',
		'collection' => 'my-icons',
		'categories' => array(
			'arrows',
		),
	)
);

register_icon(
	'my-plugin/arrow-down',
	array(
		'label'    => __( 'X', 'gutenberg' ),
		'filePath' => __DIR__ . '/arrow-down.svg',
		'collection' => 'my-icons',
		'categories' => array(
			'social',
		),
	)
);

[mikemcalister]

Thanks for everyones work on this so far! I agree with the others, the ability to register a custom icon set will be critical. Builders and agencies will want to ship custom icon sets for their clients and product creators will want to ship custom icon sets for their user base.

I was rallying for this to make v1 of the icon block, but looks like it might have to wait?

[pbearne]

Lets use these for the admin icons

[mrwweb]

Just echoing @mikemcalister a little more bluntly: I am super excited for this block, but it won't be very much use to me until I can register my own icons.

I like the thought of a manifest file as a means of registering them. Other ideas for custom icon registering can be found in the Icon Block plugin's repo.

Most of those include ways of defining an icon's category and keywords/synonyms in the registration function or registry file.

[eric-michel]

...it won't be very much use to me until I can register my own icons.

Very much agree with this. Love that we have an icon block, but it's critical that I can add my own.

I would like the Button block to support setting an icon.

This would also be a huge value add for us and our clients. I'll add that being able to use icons in place of the markers for list items would be amazing too.