Icon API

I need to...	Guide	Summary
Understand the Icon API system	What is Icon API	You need a unified, performant system for managing icons across your Drupal 11.1+ site rather than manually handling SVG files, icon fonts, or external resources in templates and CSS. Icon API provides the core infrastructure; the UI Icons…
Understand icon pack discovery and lifecycle	Icon Pack Architecture	You need to understand how icon packs are discovered, loaded, and rendered to design efficient icon systems or troubleshoot icon discovery issues.
Create a new icon pack in YAML	Icon Pack Definition	You're creating a new icon pack in a theme or module and need the complete YAML structure with all required and optional properties.
Choose the right extractor for my icons	Choosing Extractors	You need to select the appropriate extractor plugin for your icon source format and security requirements.
Use individual SVG files	SVG Extractor	You have individual SVG files stored locally in your theme or module and want automatic discovery, sanitization, and template rendering.
Use SVG sprite files for large icon sets	SVG Sprite Extractor	You have large icon sets (50+ icons) in SVG sprite format and want optimal performance with single-file loading.
Use any image format or remote sources	Path Extractor	You need maximum flexibility for any image format (SVG, PNG, WebP) from local or remote sources, and don't need content manipulation.
Integrate existing icon fonts	Font Extractor	You have existing icon fonts (TTF, WOFF, WOFF2) with codepoint metadata files and want to integrate them with Icon API. The font extractor is provided by the UI Icons contrib module (not Drupal core).
Add icon fields, menu icons, or CKEditor integration	UI Icons Module Features	You need icon integration beyond rendering in templates: icon field types, menu icons, CKEditor embedding, or icon browsing UI for content editors. UI Icons is a contrib module that extends core Icon API functionality.
Understand template variables	Template Variables	You're writing icon pack templates and need to understand available variables and how to use them effectively.
Render icons in Twig templates	Twig Icon Function	You need to render icons in Twig templates with type safety, caching, and settings support.
Build SDC components with icon props	SDC Icon Props	You're building Single Directory Components that need configurable icons as props for reusable, flexible component APIs.
Use icon slots in components	Icon Slots	Your component needs maximum flexibility for icon content, including custom SVG, multiple icons, or complex icon compositions.
Access icons programmatically in PHP	IconPackManager Service	You need programmatic access to icon packs and icons in PHP (controllers, services, forms, preprocess) rather than templates.
Understand icon caching	Caching Strategy	You need to understand Icon API caching behavior to optimize performance or troubleshoot cache-related issues.
Optimize icon performance	Performance Best Practices	You're optimizing icon rendering performance for large-scale sites with many icons or slow networks.
Handle SVG security and optimization	SVG Security & Performance	You're working with SVG icons and need to understand security implications and optimization techniques.
Secure remote icon sources	Remote Resource Security	You're loading icons from CDNs or external sources and need to understand SSRF, mixed content, and availability risks.
Debug icon discovery issues	Troubleshooting Icon Discovery	Icons aren't appearing, pack definitions aren't loading, or icon IDs aren't resolving correctly.
Debug template rendering issues	Debugging Templates	Icons render incorrectly, template variables are missing, or SVG markup is malformed.
Migrate from existing icon systems	Migration Patterns	You're migrating from manual icon management, icon fonts, or other icon systems to Icon API.
Build a custom extractor plugin	Custom Extractor Development	Core extractors (SVG, SVG Sprite, Path, Font) don't support your icon source (API, database, generated icons, external service).