Add an icon management API

Problem/Motivation

In core

There are at least 141 icons in Drupal Core, living in many folders:

• misc/icons/{group}/{icon_id}.svg
• misc/icons/{icon_id}.gif
• misc/{icon_id}.gif
• misc/{icon_id}.png
• modules/media/images/icons/{icon_id}.png
• the ones from umami theme
• the ones from claro theme
• the ones from olivero theme
• the ones from starterkit_theme theme
• ...

Used by the modules in many ways...

... from CSS backgrounds:

modules/options/css/options.icon.theme.pcss.css:  background-image: url(../../../misc/icons/55565b/selection_list.svg);
modules/ckeditor5/css/drupalmedia.css:  background: url("../../../misc/icons/e29700/warning.svg") no-repeat center 4px;
modules/settings_tray/css/settings_tray.theme.css:  background-image: url(../../../misc/icons/bebebe/pencil.svg);
...

... from PHP:

modules/filter/filter.module: $image->setAttribute('src', base_path() . 'core/misc/icons/e32700/error.svg');
modules/update/update.report.inc: $uri = 'core/misc/icons/73b355/check.svg';
modules/system/tests/modules/ajax_forms_test/src/Form/AjaxFormsTestImageButtonForm.php: '#src' => 'core/misc/icons/787878/cog.svg',
...

... from Twig:

modules/navigation/templates/toolbar-button.html.twig: icon ? 'toolbar-button--icon--' ~ icon : '',
modules/update/templates/update-project-status.html.twig: {{ status.icon }}
...

However:

• This usage is unorganized. If an icon is moved or changed, we need to manually track its usage
• Everything is hardcoded. There is no UI to use or change those icons from admin pages
• There is no way for themes to override icon packs or individual icons, in order to adapt them to specific branding

Having a well established API will make this possible.

In contrib

There are many modules providing icons management for Drupal 10 and/or D11. However, most of them are dedicated to a specific icon pack:

• material_icons
• fontawesome
• fontawesome_menu_icons
• menu_bootstrap_icon

Or a specific remote service:

• iconify_icons
• micon (icomoon)
• md_fontello
• iconify_field

Hopefully, there are few agnostic icon management modules:

• iconset
• icons
• ui_icons

Anyway, there are a lot of duplicate work on those modules:

• On the lower (API) level: most of them are providing Form Element, Render Element, Twig Function… which works more or less the same and can be unified
• On the higher level: they provide more or less the same integration with Drupal API (fields, menus, media, ckeditor5, etc.)

A common Core API will allow those modules to focus on the specific value they are bringing to the Drupal community, instead of duplicating the same features over and over.

Modules with icon integrations:

• External Links: #3482227: Support UI Icons

Proposed resolution

The starting point

We need an unified API to declare icon packs, retrieve the icons list, and interacts with each icon (form, render, metadata…). And it is better to start from an existing implementation from contrib space.

Among the agnostic modules, we propose to get inspiration from ui_icons because:

• iconset is not front-dev friendly enough (icon sets delcaration in YML and icon handling in PHP are separated, but the later do too much) and has a dependency to toolshed
• icons is not front-dev friendly enough (icon library declaration and icon extraction process are merged in a PHP class)

Also, ui_icons have those advantages:

• Tested with many icon packs: bootstrap, dsfr, feather, fontawesome, heroicons, icomoon, material, octicons, phosphor, remix, uswds...
• Small & clean API: 22 PHP files, 1 177 lines of code, 1 022 lines of comments. Already 95% of tests coverage.
• Built by the UI Suite team which is dedicated to design systems implementation in Drupal since early 2020 (early 2017 if we count the early efforts), so with a deep care for design & site building needs.

(Disclaimer: I am part of UI Suite and one of the maintainers of the ui_icons module)

The main module of ui_icons is providing those elements:

• a definition class for icons
  

  icon_id
  source: URL or path of the icon
  data: additional data generated by and specific to the extractor
  group
  

• a plugin manager for icon packs with a YAML discovery, which is front-dev friendly (declarative, straightforward, without drupalism, using JSON schema)
• a plugin manager for extractors with a PHP attribute discovery, to build the icon list from the icon pack definition
  

  function discoverIcons(): array;
  function label(): string;
  function description(): string;
  static function createIcon(string $icon_id, string $path, array $data, ?string $group = NULL): IconDefinition;
  function getFilesFromSources(array $sources, array $paths): array;
  

• a render element and the related Twig function:
  

  [
   '#type' => 'icon',
   '#icon_pack' => 'material_symbols',
   '#icon' => 'home',
   '#settings' => ['width' => 64],
  ]
  

• a form element
  

  [
   '#type' => 'icon_autocomplete',
   '#title' => $this->t('Select icon'),
   '#default_value' => 'my_icon_pack:my_default_icon',
   '#allowed_icon_pack' => ['my_icon_pack, 'other_icon_pack'],
  ]

• a few extractor plugins: Manual declaration (to be confirmed), Local path, SVG, SVG Sprite, and Font/Codepoint (to be implemented)

Proposal 1: low-level, complete API

In this proposal, we simply take everything the main module is providing.

Then, every contrib module (including UI Icons which is still relevant) can provide higher level features:

• Icon library, to browse icons from the user interface
• Alternative icon pickers form elements
• Integration with various Drupal Core & Contrib API
• New extractors, including niche formats and integration with remote services
• ...

Proposal 2: still low-level, but compact API

We take only what would be needed by core today, so without the form element and most of the extractors:

• the definition class for icons
• the plugin manager for icon packs with a YAML discovery
• the plugin manager for extractors with a PHP attribute discovery
• the render element and the related Twig function
• the extractor(s) needed for Core icons (Local path?)

Remaining/others tasks

First, let's decide what are we proposing for integration.

About naming, is it possible to claim /project/icon namespace? This (popular, 6,500 installs) module is deprecated, unsupported, unmaintained since 2017 and Drupal 7 era.

Once implemented, it would be great for Drupal Core to define icon pack(s) for its own icons and start to use them in PHP and Twig.

User interface changes

No, because the module will not provide integration with Drupal admin pages (ckeditor5, field management, menu management...), at least at the beginning, but contrib modules like UI Icons will do that. We hope to see an ecosystem emerging, and existing modules migrating to the new API.

Introduced terminology

"Icon", "Icon pack", "Extractors"... what else?

API changes

No, we add a new API but we don't change existing.

Data model changes

No.

Release notes snippet

To be done.