UI Icons
A generic icon manager for Drupal that seamlessly integrates third-party icon packs using Drupal's core Icon API.
ui_icons
Overview
UI Icons is a comprehensive icon management system for Drupal that provides a unified way to integrate, manage, and display icons from various third-party icon packs. Built on Drupal's core Icon API (introduced in Drupal 11.1), it offers seamless integration throughout the Drupal ecosystem including fields, menus, text editors, media entities, and UI Patterns.
The module provides an extensible architecture with multiple submodules for specific integrations. Icons can be discovered from various sources including SVG files, web fonts (TTF/WOFF), codepoint files, JSON, and YAML configurations. The intelligent search system uses fuzzy matching with priority-based results and caching for optimal performance.
Key capabilities include an autocomplete form element for icon selection, a visual picker modal, text filters for embedding icons in content, CKEditor 5 integration, field types and widgets for icon and link fields, and menu link icon support with customizable display positions.
Features
- Icon Pack Discovery: Automatically discovers and loads icon packs defined in *.icons.yml files from modules and themes, supporting multiple extractors (path, SVG, font, sprite)
- Autocomplete Form Element: Provides an icon_autocomplete form element with intelligent fuzzy search that prioritizes exact matches, word order matches, and partial matches with configurable result limits (default 24, max 132)
- Visual Icon Picker: Modal-based icon picker (icon_picker) for intuitive icon selection with grid display and AJAX pagination
- Icon Library Browser: Admin interface at /admin/appearance/ui/icons for browsing all available icon packs with search, filtering by group, and paginated display (100 icons per page)
- Field Type Integration: Icon field type (ui_icon) for entity fields with configurable allowed icon pack restrictions
- Link Field Widget: Extended link field widgets (icon_link_widget) for adding icons to link fields with position options (before, after, icon only)
- Text Filter: Embed icons in content using <drupal-icon> tags with the icon_embed filter, supporting custom settings and accessibility attributes
- CKEditor 5 Integration: Visual icon insertion in the rich text editor with a dedicated dialog for icon selection and settings
- Menu Icon Support: Automatically adds icon selection to menu link content entities with configurable display positions and integration with the Navigation module toolbar
- Media Source: Icon media source plugin for creating reusable icon media entities with full metadata support including pack ID, label, license, and source information
- UI Patterns Integration: Icon source plugin for UI Patterns 1.x and 2.x with icon prop type support
- Web Font Extractor: Extract icons from web fonts (.ttf, .woff), codepoint files, JSON, and YAML definitions using the dompdf/php-font-lib library
- Twig Extension: icon_preview(pack_id, icon_id, settings) Twig function for rendering icon previews in templates
- Theme Compatibility: Automatic CSS adaptation for Gin, DaisyUI, and DSFR admin themes
- Caching System: XXH3 hash-based search caching with icon pack and collector cache tags for optimal performance
- Settings Management: Per-icon extractor settings support with dynamic form generation based on icon pack configuration
Use Cases
Adding Social Media Icons to Content
Enable UI Icons Fields and add an Icon field to your content type. Configure allowed icon packs to limit selection to your social media icon pack. Use the autocomplete or picker widget for content editors to select icons. Display using the icon formatter with custom size settings.
Creating Icon-Enhanced Navigation Menus
Enable UI Icons for Menu to automatically add icon selection to menu link editing. Editors can select icons for each menu item and choose display position (before text, after text, or icon only). Icons are automatically rendered in menu output with proper markup.
Embedding Icons in Rich Text Content
Enable UI Icons Text and UI Icons for CKEditor 5. Configure your text format to enable the Embed icon filter with allowed icon packs. Users can insert icons using the CKEditor toolbar button. Icons render as <drupal-icon> tags in content and are processed on display.
Building a Reusable Icon Media Library
Enable UI Icons Media and create an Icon media type. Content editors can add icons to the media library for reuse across content. Media icons include full metadata (pack, license, source) and automatic thumbnails for visual browsing.
Theming with Icon Integration
Use the icon_preview Twig function in your theme templates: {{ icon_preview('my_pack', 'icon_id', {size: 24}) }}. Icons render using the pack's defined template or the fallback icon-preview.html.twig template.
Creating Custom Icon Packs
Define icon packs in your module or theme using *.icons.yml files. Specify extractor type (path, svg, font, sprite), source files, and optional settings forms. The Icon API automatically discovers and registers your icons for use throughout the site.
Tips
- Use the grid result format for icon autocomplete when working with icon packs that have many similar icons - the visual grid helps distinguish between them
- Enable the UI Icons Library submodule during development to browse and test your icon packs before integrating them into content
- For performance, limit allowed icon packs on fields to only those packs actually needed - this reduces search scope and improves autocomplete speed
- When using icon_embed filter, always include proper ARIA attributes (aria-label or aria-hidden) for accessibility compliance
- The search uses fuzzy matching with priorities - exact word matches appear first, making common naming conventions (action-arrow-right) highly searchable
- Icon settings are stored per-pack, allowing different visual configurations for the same icon in different contexts
Technical Details
Admin Pages 2
/admin/appearance/ui/icons
Browse all available icon packs on your site. Displays a card grid of icon packs with previews (up to 32 random icons per pack), pack name, description, version, license information, and total icon count. Includes toggle to show/hide disabled packs.
/admin/appearance/ui/icons/{pack_id}
Search and browse icons within a specific icon pack. Provides keyword search, group filtering, icon settings configuration, and paginated display of 100 icons per page at 64px size.
Permissions 1
Hooks 4
hook_preprocess_menu
Preprocesses menu items to add icon markup based on icon options stored in menu link URLs. Handles before, after, and icon_only display modes.
hook_link_alter
Alters links to display icons in admin menu management context (/admin/structure/menu/manage) for links with icon options.
hook_navigation_menu_link_tree_alter
Alters the Navigation module menu link tree to support icon display with proper class settings for toolbar integration.
hook_entity_base_field_info_alter
Alters the link field on menu_link_content entities to use the icon_link_widget widget, enabling icon selection on menu links.
Troubleshooting 5
Ensure icon packs are properly defined in *.icons.yml files with correct extractor and source configuration. Clear caches after adding or modifying icon pack definitions. Verify the icon pack is not marked as disabled.
Check that the text format has icon_embed filter enabled and positioned after filter_html and filter_autop filters. Ensure <drupal-icon> tag is allowed in HTML restrictions with required attributes: data-icon-id, data-icon-settings, class, aria-label, aria-hidden, role.
Install the dompdf/php-font-lib library using Composer. Verify source files are correctly specified in your icon pack definition with proper file extensions (.ttf, .woff, .codepoints, .json, .yml).
Check the field's 'Allowed icon packs' setting. If specific packs are selected, only those icons will be available. Leave empty to allow all packs.
Verify your theme's menu template properly renders the $item['title'] which includes the icon markup. The icon is rendered inline with the link text using FormattableMarkup.
Security Notes 3
- The icon_embed filter properly sanitizes HTML attributes to prevent XSS when rendering user-provided icon settings
- Icon autocomplete endpoints require 'access content' permission to prevent unauthorized icon enumeration
- The UI Icons Library requires 'access ui icons library' permission, keeping icon browsing restricted to authorized users