Can the Icon Registry resolve through a provider, without requiring SVG markup or glyph enumeration?

[Jiwoon-Kim]

A question about the Icon Registry's data model, raised now because the answer is
cheap to keep open at this stage and awkward to introduce afterwards.

This is deliberately separate from the SVG-first migration in
#81225 and
#82062, which move Core's
hardcoded UI SVGs onto stable identifiers. That work is the right shape and should
land; nothing here is a request to change it. It is also separate from
#82228, which is about
what an icon-only control is. This one is about what an icon reference resolves
to.

What the model assumes today

wp_register_icon() takes content (SVG markup) or file_path, and "if both
content and file_path are not set, the icon will not be registered".
wp_register_icon_collection() takes only label and description, so a
collection is metadata about a group rather than something that can resolve a name
inside it.

Both halves therefore assume the same thing: an icon is markup, held per icon.

Where that assumption is visible

Icon fonts are the case that does not fit, and not because of effort. With a
ligature-based font the name is the input:

<span class="material-symbols-outlined">arrow_forward</span>

Nothing needs registering per glyph for that to work. Someone looks a name up in the
font's public catalog and types it. There is no list for WordPress to hold, and a
theme that already loads such a font would have to re-express its icons as
registered SVG entries to participate — not because the icons are missing, but
because the registry's unit of registration is an SVG.

So the two kinds of source differ in what gets registered, not only in what comes
out:

SVG set    →  register each icon    →  enumerable, so a picker is possible
icon font  →  nothing to enumerate  →  the name is typed

A second difference: where interaction state lives

An icon-only control has states — hover, focus, pressed, selected. With one
registered SVG per icon, expressing "selected" means naming a second icon
(favorite and favorite-filled), so the state ends up represented in the icon
reference, which is to say in the content layer. If an icon-only control ever grows
a "selected icon" field, that is this model surfacing.

A variable font keeps it out of there. A theme can register the fill axis as a typed
custom property:

@property --md-icon-fill {
	syntax: "<number>";
	inherits: true;
	initial-value: 0;
}

.material-symbols-outlined {
	font-variation-settings: "FILL" var(--md-icon-fill, 0), …;
	transition: --md-icon-fill 150ms …;
}

and a control then expresses only its semantic state, never the glyph:

.some-control__button:hover .material-symbols-outlined,
.some-control__button.is-selected .material-symbols-outlined {
	--md-icon-fill: 1;
}

One glyph interpolates outline → filled on hover and selection. The control names a
state, the theme decides what that state looks like, and the icon system is involved
in neither. That mapping is the theme's to make and should be. The only question for
Core is whether the icon layer forecloses it.

The question

Can the icon layer preserve an opaque reference and delegate rendering to a
provider, without requiring that provider to enumerate every available glyph or
resolve to SVG markup?

Sketched, the shape would be:

icon reference
  → a provider resolves it
  → the provider emits SVG, a font span, or something else

Whether a provider can enumerate what it offers — and therefore whether a picker is
possible for it — becomes the provider's own property rather than something the
registry assumes of every source.

I am not proposing an implementation, and specifically not proposing that icon fonts
be supported now. The narrower question is whether an icon reference should stay
separate from the markup that currently realizes it, so that the same reference
could later be resolved differently without changing what blocks have stored.

Context

I maintain a block theme whose icon language is a variable font, which is how I ran
into this; the state-mapping example above is from it. I am not suggesting Core
adopt that approach — only that a registry which can only answer with SVG markup
would rule it out, and it is not obvious that ruling it out is intended.

[meyshad]

Yes. I think the stored icon reference should be separated from its rendering now, before consumers start depending on SVG being the storage format.

A block or control only needs to persist an opaque reference:

type IconReference = {
    provider: string;
    name: string;
    variant?: string;
};

The provider can then decide whether that reference becomes SVG, a font ligature, or another constrained element. Enumeration should be an optional discovery feature, not a registration requirement.

A PHP API could have roughly this shape:

wp_register_icon_provider('material-symbols', [
    'render_callback' => static function (array $icon): string {
        $name = $icon['name'] ?? '';

        if (! preg_match('/^[a-z0-9_]+$/', $name)) {
            return '';
        }

        wp_enqueue_style(
            'material-symbols',
            'https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined'
        );

        return sprintf(
            '<span class="material-symbols-outlined" aria-hidden="true">%s</span>',
            esc_html($name)
        );
    },

    // Optional. Providers with a large or remote catalogue can implement search
    // without registering every glyph up front.
    'search_callback' => null,
]);

The editor would need the equivalent JS provider so previews match front-end rendering. If a provider is unavailable, Core should render a predictable fallback rather than retaining provider-generated HTML in block attributes.

A few boundaries would keep this safe and portable:

• stored content contains only provider, name, and an optional visual variant;
• the provider validates the name and owns sanitization/enqueued assets;
• arbitrary classes or HTML are not accepted from block attributes;
• accessible text belongs to the surrounding control; a decorative icon stays aria-hidden;
• variable-font state such as fill or weight remains CSS/control state unless it represents a real named variant.

This also permits providers backed by APIs: search_callback can return paginated results on demand, while a known opaque reference can still be resolved without downloading the complete catalogue.

[Jiwoon-Kim]

This makes me think there are two distinct cases.

When an author chooses a pictogram, an opaque provider / name / optional
variant reference is the right shape.

A fixed UI control is different. A light/dark/auto switcher does not ask an
author to choose its sun or moon; the block owns the action, state, and
accessible name, while the active theme owns the icon language and its visual
state. A theme can already provide that through an icon font, with selection
expressed through CSS rather than a second stored icon reference.

That is the model used by my Theme Switcher block. It works with its companion
theme today; the portability problem is that the block must currently know the
theme's font class and ligature names. I do not think that implies a semantic
slot API should be designed in this thread. It does reinforce the narrower
question here: a provider-based Icon Registry should not require SVG markup or
enumeration as the only way for a theme-provided icon language to participate.

A future block-to-theme contract for fixed semantic UI symbols may be a
separate layer above icon references, but it seems useful not to foreclose it.