UI Icons
Philosophy: Wrap Drupal core's Icon API (11.1+) with discoverable icon-pack plugins, the font extractor, and integrations across Field API, CKEditor 5, UI Patterns, Menu links, Media, Drupal Canvas, and Twig — so any icon set becomes available throughout Drupal via one YAML declaration per pack.
I Need To...
| I need to... | Guide | Summary |
|---|---|---|
| Understand what UI Icons does and when to use it vs alternatives | Overview | Use UI Icons when editors need a picker UI across fields, CKEditor 5, menus, UI Patterns, media, or Canvas. Documents 2.0.0 but verified only against 1.1.2 — 2.0.0-only claims (Canvas, submodule set, core range) are unverified. |
| Install UI Icons and enable the right submodules | Installation | Composer-require drupal/ui_icons, then enable submodules per integration needed. The submodule inventory and the ^11.3||^12.0 range are unverified 2.0.0 claims — 1.1.2's effective floor is Drupal 11.1+, since only ui_icons_backport states ^11.1 outright and the rest depend on the base module anyway. |
Author an icon pack in YAML (*.icons.yml) |
Icon Pack Format | Declare pack_id, extractor, config.sources, optional settings, and a required Twig template in {module|theme}.icons.yml at the extension root. Omitting template throws an exception, not blank output; a library: key is the only way to attach CSS/@font-face to a pack. |
| Choose between path / svg / svg_sprite / font extractors | Extractors | Use svg for individual SVG files needing inline content, svg_sprite for a single sprite sheet, path for URL-referenced files, and font (ui_icons_font) for TTF/WOFF packs. Only font ships from UI Icons; the other three live in Drupal core. Never print font content bare — it isn't a glyph. |
| Define configurable per-icon settings (size, color, decorative) | Settings & Rendering | Declare settings as typed properties (size, color, decorative, variant); build the template to switch aria-hidden/role/aria-label on a decorative boolean. Always include decorative plus an alt/ariaLabel setting for WCAG compliance. |
| Wire icons into a Drupal field | Field API Integration | Enable ui_icons_field and add a ui_icon field; the widget stores pack_id:icon_id in target_id (verified on 1.1.2). mainPropertyName/ICON_ID_PCRE and the whole ui_icons_canvas subsection are unverified 2.0.0-only claims. |
| Make an icon prop editable in the Drupal Canvas builder | Field API Integration | Enable ui_icons_field and add a ui_icon field; the widget stores pack_id:icon_id in target_id (verified on 1.1.2). mainPropertyName/ICON_ID_PCRE and the whole ui_icons_canvas subsection are unverified 2.0.0-only claims. |
| Embed icons inline in CKEditor 5 | CKEditor 5 Integration | Enable ui_icons_ckeditor5 + ui_icons_text, add the Icon toolbar button and Embed icon filter to a text format. The passthrough attributes land on a wrapper , not the pack's own markup, and aria-hidden="false" inverts to a bare aria-hidden — omit it instead. |
| Use icons as UI Patterns props | UI Patterns Integration | Enable ui_icons_patterns to register the icon PropType (pack_id, icon_id, settings) and four data sources. An icon prop is plain data, not a renderable — call icon(prop.pack_id, prop.icon_id, prop.settings) in the template, or use a slot fed by icon_renderable. |
| Attach icons to menu links | Menu Integration | Enable ui_icons_menu to add an icon widget to the menu_link_content form. Three hooks inject the icon markup into link titles automatically — no preprocess or template override is needed, and there is no data-icon-id attribute to read. |
| Render icons in Twig templates | Twig Rendering | Use core's icon(pack_id, icon_id, settings) as the general renderer in theme templates; needs no contrib module. icon_preview() is the admin-preview renderer and forces size 48 (not the pack's own default) when settings are omitted. |
| Add icons to media entities | Media Integration | Enable ui_icons_media and create a media type with source plugin Icon; each entity stores pack_id:icon_id plus optional settings. Use Field API or CKEditor integrations instead when reuse across pages isn't needed. |
| Browse all packs in the admin UI | Library Admin | Enable ui_icons_library and visit /admin/appearance/ui/icons to browse packs and preview icons with a fuzzy search bar. Requires access ui icons library; clear cache after adding icons since YamlDiscovery caches pack contents. |
| Ship a custom icon pack from a theme/module | Authoring & Distribution | Place SVG assets at the theme/module root, declare the pack in {name}.icons.yml with extractor/config/settings/template, then clear cache. A CSS library needs two edits — declare it AND point the pack's library: key at it, or nothing attaches. |
| Find pre-built community icon packs | Pre-built Pack Catalog | The community UI Icons Example repository provides starting-point *.icons.yml declarations for Bootstrap Icons, Heroicons, Lucide, FontAwesome, and more — copy, adapt, add the icon files. Several UI Suite themes already bundle a pack. |
| Avoid common mistakes (caching, a11y, SVG XSS) | Anti-Patterns | Never trust SVG as fully sanitized — UI Icons does not strip
|