Icon/Vector registration API

[draganescu]

Demo repo

https://github.com/draganescu/wp-icon-api/tree/trunk

Icons!

Icons communicate condensed information and expectations of what happens after an action. Given that the site editor is a design tool, for professionals and enthusiasts alike, there are countless situations that require a good icon: a call to action button that shows some love, a menu item that is special for 15 days, the visual highlight of a blog with well curated quotes, landing page sections that allow better conversions because icons make skimming easier, a quick logo solution, I could go on and on.

Prior art

The 1st path explored was allowing users to upload SVG files which could then be used directly. That did not and still does not work. Starting with the long discussion in Reconsider SVG inclusion to get_allowed_mime_types and up to the recent attempt of a trimmed down option in Performance Lab plugin’s SVG uploads letting normal author users simply uploading, previewing and inserting untrusted SVG content is hard to do in a secure manner. With thousands of security concerns and a format that is too flexible to properly sanitize, allowing low permission users uploading SVG as media is hard to do right.

So how about a 2nd path?

Proposal

Instead of allowing low permission users uploading SVG as media, we allow high permission users to install plugins which provide secure SVG media.

SVG is complex, let’s restrict the discussion here only for using the format for icons.

As suggested before, I propose a system of registering SVG icons one by one in plugins. These plugins register icons just like they register blocks, with some function like:

register_icon('my-plugin/book', {
	title: 'Book',
	icon: 'icons/book.svg', // or simply the SVG directly
	tags: 'book, lecture, paper, hardcover',
	category: 'decoration',
});

Or, even better, we could have a more general API like:

register_vector('my-plugin/book', {
	type: ‘icon’,
	title: 'Book',
	icon: 'icons/book.svg', // or simply the SVG directly
	tags: 'book, lecture, paper, hardcover',
	category: 'decoration',
});

The second register method would allow vectors that are more than icons to be used in various ways: decoration, masking, featured content.

Either way, the goal is to make SVGs available from trusted sources.I

Similarly to registering block collections we could also support registering icon collections, just for the same reasons, to visually group these icons where users can browse them.

All icons and collections registered should be available via the REST API in some wp-json/wp/v2/icons resource. The resource returns collections by default, supports searching for an icon and listing icons in collections and tags.

In the block editor we introduce a new supports: icon,.

If a block supports using icons, a new control shows up in the design panel allowing a user to browse for icons and search for an icon. The block’s edit and save components can implement how they see fit the icon once the user chooses it, and Ideally they copy the SVG into markup or meta. The icon in the block inherits the default block styling (colors).

If we want to allow users to use standalone icons we can also add an icons block that only displays an icon and allows for styling it. If we implement this then the inserter could as well sport a nice icons tab searching through the same registered icon packs from plugins.

This option allows the ecosystem to provide curated and secure vector graphics, people with accurate permissions to curate these plugins before choosing them, and finally users to use vector graphics - albeit initially just for iconography for now - in their design and content.

What do you think? Is this a terrible idea? Can it be built upon?

[getdave]

Thanks for developing this into a discussion.

Thank you for raising this. It's a good suggestion and one that is needed by users and developers.

As #51563, I propose a system of registering SVG icons one by one in plugins. These plugins register icons just like they register blocks, with some function like:

What is being proposed is actually just an API for registering icons. I assume it could also be used by Core itself as well as the Plugins you mention?

All icons and collections registered should be available via the REST API in some wp-json/wp/v2/icons resource

This is very important. Why? Because currently all icons are either custom or from @wordpress/icons. Both of those solutions are client side focused which means when you want to use an icon on the block's front end render (i.e. using PHP) you have to hardcode it into the markup 😓

As I previously suggested, the API should allow for the icon markup to be registered as HTML and then it can be consumed via

• PHP - escape and output.
• JavaScript (React) - probably requires dangerouslySetInnerHTML as the SVG would not be React components.

The use cases for this as many, but in Core there are already scenarios where it would be useful for Plugins to be able to register icons in order that they can be offered as additional options to users. The one I'm thinking about is (unsurprisingly!) the "hamburger" mobile toggle icon for the Navigation block. In this scenario icons could be registered and then added to the block editor settings (as references - by ID?) allowing them to be consumed by the Navigation block which would simply request the appropriate icons and display in the UI controls.

## Other options to consider

I have previously received feedback (away from Github) that we could consider using Theme JSON as the place to register the icons. I'm not sure of the implications of that. Perhaps @oandregal can offer his input here?

[getdave]

I think this API has nothing to do with @wordpress/icons. System icons will still be part of that package. This is for user icons. Also what is wrong with hardcoding? As I suggest:

I may have not been clear. What I'm saying is that your proposal sounds really good and will work well and help avoid the current problems of consuming @wordpress/icons.

[oandregal]

As for how theme.json plays into this: I don't see icon registration primarily relying on theme.json.

Icons would have assets (svg, etc.) and those are better managed through a dedicated API. This may be similar to custom fonts. I think @matiasbenedetto and @hellofromtonya were exploring this. I don't know the details, though it was discussed investigating the existing Attachment API or developing their own.

Sure, at some point icons may interact with theme.json for specific things (for example, enabling/disabling icons functionality per block, providing a list of registered icons like presets do, etc.). The theme.json API works best when there is something (styles, settings) that can be set by different origins (core, blocks, theme, user). Note that plugins interact with theme.json by using the filters (so a first-class citizen).

[hellofromtonya]

Icons would have assets (svg, etc.) and those are better managed through a dedicated API. This may be similar to custom fonts. I think @matiasbenedetto and @hellofromtonya were exploring this. I don't know the details, though it was discussed investigating the existing Attachment API or developing their own.

Before diving into API discussions, I'd suggest first exploring how users could manage icons, i.e. icon management user experience and workflows. Start with the user in mind.

Fast forwarding to today (i.e. in retrospective), font management started (years ago) with technical discussions of registration, enqueuing, and handling, rather than with the user and how fonts would be presented to them for their interaction and decisions.

Could icon management use similar artwork and workflows of the Fonts Library?

[draganescu]

My proposal is describing the user facing part as much as I think it'll be useful:

• blocks that support icons will show a control in the inspector which allows users to search and pick the icon they want.

I do not think that for icons we need a media library style UI - too much.

If the API ends up as a more generic one and say people can make plugins that register SVG for any content - then yes larger artwork will need is own modal experience for finding what you want.

[Ren2049]

A centralized media asset manager or "interactive CDN" on wp.org and/or wp.com could work a lot better. Somethink that works alongside the remote pattern library and is manageable by users and supports icons, fonts, images. The infrastructure for this basically already exists (Openverse, Jetpack CDN etc.).

The asset management could happen right within the media library view, with a opt-in/out setting in settings or future setup wizards.

A service like that could also help to spice up the remote pattern library and work hand in hand where your own image assets could be included within other remote patterns and in their previews.

Every theme could have it's own default asset collection, and the incentive for Automattic to pour more resources into a service like this could be the prospect of a graphics asset marketplace. I'd expect that font and icon foundries or existing graphic asset stores would also be very interested in hooking into this.

This service could have plugins for image editing and design tools with plugin support like Figma, Canva (they support plugins now), PS etc. where designers/users can upload their assets with a click and also make them discoverable by other users.

With a CDN there's also the beenfit to optimize the image assets in one go (svgo, webp, font subsetting).

[draganescu]

I created a demo repo about how this could work https://github.com/draganescu/wp-icon-api/tree/trunk

[draganescu]

In the repository the following are demonstrated:

• there is a plugin that creates a globally available icon registration function
• a sample.php file shows how multiple SVG icons can be easily registered
• the plugin creates two REST endpoints, one that lists all registered icons, one that searches through them
• a block is also registered
  • the blocks shows how the SVG can be saved an rendered
  • the block demos an inspector panel that should be provided by Gutenberg to any block that supports: icons.

[fabiankaegy]

I just want to share that I have done a similar exploration here:

https://github.com/10up/block-components/tree/develop/components/icon-picker
https://github.com/10up/block-components/tree/develop/api/register-icons

Having something similar in core would be super useful!

Also, making it available through theme.json to make a subset of icons available to different blocks would be very nice. Currently, the limited hardcoded set of icons for the navigation block for example could very nicely be swapped out by custom registered icons.

[fabiankaegy]

Also there are two different things I kind of mixed.

1. The ability for only certain icons to be available in some blocks
2. The ability to register different sets of icons that are separated in the UI. (Like Custom Icons | Core Icons | Google Material Icons | Fontawesome Icons etc)

[draganescu]

In my proposal above any block that supports icon should then automagically get an inspector control that allows for searching / filtering in existing icons. Do you think we need more strict control? What is the downside of allowing access to all icon library at any point?
In this proposal here to restrict ouf of all registered icons only a subset for one block we'd need a sort of "context" prop in the registration function. That could work. Then the supports will only search through the icons available for said context.

[fabiankaegy]

Hmmm yeah I'm not sure what the right answer would be. The scenario I'm thinking about here is that for the navigation block for example, ideally we would have a way to say only the menu /expansion type icons would be available.

Taking again the Material Icons example. There are about ~2500 icons in there. And even with the search box it is sometimes a little cumbersome to have to search through thousands of icons when there are maybe max 20 icons in there that are actually applicable to what you are trying to do.

I can see how that is adding a lot of complexity though and if we make it easy enough to add keywords etc like you are suggesting maybe the ability to search icons is good enough.

In the end we won't be able to protect users from themselves if they really want to use a smiley face as their menu opening icon.

[ndiego]

I agree with the need to be able to limit icon "sets" per block type. For example, a Button block might be able to add a handful of arrow icons, and the Navigation block could menu /expansion type icons. Then there could, of course, be a dedicated icon block that offers everything.

I think the restriction settings should be configurable by the site creator. By default, blocks that opt into icon support get everything, but there should be a way to curate what icons are available per block type if you want. This would make this functionality much more usable from the perspective of those building sites for clients.

[audunmb]

Wouldn't the limitation to finding the right icon for your block be solved by categories. So instead of searching trough all icons, you can choose Arrows, and then find the arrow icon you want. This is how it works in your Icon block, @ndiego, and would make sense when adding svgs elsewhere. Limiting what can be used might not be necessary if it's easy to find what you need.

This will also make sense if use SVGs for other things than icons, such as dividers or ornaments. While it could be possible to insert an ornamental SVG into a button, very few would look in the Ornaments category for a down arrow.

[fabiankaegy]

@draganescu How can I help move this proposal forward? :) Are you currently working on developing this further?

[draganescu]

I think the next step would be to open a Gutenberg PR with:

• the icon registration API
• the block support implementation
• the core icons registered

[talldan]

Sharing some thoughts:

• Icon sets seems like an important concept, especially if the main purpose of this API is to allow for an ecosystem of icons. Users would expect icons from the same set to be grouped so that it's easy to keep a consistent design.
• A user switching between sets of icons might be a strong use case. You could imagine themes and theme variations being configured to use a set of icons, then when a user switches between them, the icons used for blocks like navigation and search could automatically change. At some point a way to nominate icons for those blocks for an icon set would be good.
• Given the above, there might also be an integration with theme.json (discussed above), and there could be no-code ways to register icons for themes (like dropping them in a folder and metadata from the svg file being read to provide the tag, category data, similar to how patterns work in a theme).
• Registering one icon at a time might be a bit cumbersome. I think most of the time the use case would be registering multiple at once.

Definitely not all things to be solved right away, starting with the most simple API seems like a good idea, but it could be worth considering those things to make sure the initial API design is flexible enough to achieve them.

[audunmb]

This would be great. There are so many plugins that add icons to things, each in their own way. Older plugins usually use Font Awesome, while newer ones use SVGs, but all load their own icons. Making the default icons in Wordpress available instead, and then adding the option of adding more when needed, would reduce the overall bloat and ensure visual consistency.

[matiasbenedetto]

the goal is to make SVGs available from trusted sources.

Assuming that WordPress can ensure the safety of a source: Can the SVG assets be handled using the media API?
Assuming WordPress can't ensure the safety of a source: What would a dedicated API endpoint for icons bring to the table?

[getdave]

What would a dedicated API endpoint for icons bring to the table?

If I understand your question correctly, I think the answer is that it would allow Editor and Front of Site to share the same icons.

I explained this a bit more in this comment.

[draganescu]

In theory yes it could. In more theory even with my pack registration API we could augment the media api to search the vector registry too.

[matiasbenedetto]

Let's say the SVG format is finally accepted in the media library. Will the dedicated API endpoints for icons still be useful?

[fabiankaegy]

Yes!

SVG images in the media library allows for img tags with the image as a source. These icons cannot get altered using CSS / JS.

The idea behind these icons here is that they should get added as svg elements on the page so they can get animated / colored etc.