UX Icons

https://github.com/symfony/ux-icons
Admin
UX Icons is a Symfony UX package that renders local and remote SVG icons in your Twig templates...
Tokens:41,551
Snippets:306
Trust Score:9.5
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install symfony/ux-icons with Composer

Source: https://github.com/symfony/ux-icons/blob/3.x/doc/index.rst

Install the package using Composer. Run this command in your terminal.

```terminal
$ composer require symfony/ux-icons
```

--------------------------------

### Install symfony/ux-twig-component

Source: https://github.com/symfony/ux-icons/blob/3.x/doc/index.rst

Installs the symfony/ux-twig-component package, required before using the HTML-based <twig:ux:icon> syntax.

```terminal
$ composer require symfony/ux-twig-component
```

--------------------------------

### ux:icons:lock CLI usage

Source: https://github.com/symfony/ux-icons/blob/3.x/_autodocs/api-reference/commands.md

Examples of running the command to lock icons, including a standard run and a forced re-download with verbose output.

```bash
# lock all on-demand icons found in Twig templates
php bin/console ux:icons:lock

# re-download everything, overwriting local copies
php bin/console ux:icons:lock --force -v
```

--------------------------------

### CacheIconRegistry get() method signature

Source: https://github.com/symfony/ux-icons/blob/3.x/_autodocs/api-reference/registries.md

Declares the get() method with a $refresh parameter that defaults to false. When true, forces recomputation by passing beta: \INF to the cache.

```php
public function get(string $name, bool $refresh = false): Icon
```

--------------------------------

### Build a custom registry chain with ChainIconRegistry

Source: https://github.com/symfony/ux-icons/blob/3.x/_autodocs/api-reference/registries.md

Create a chain of icon registries to resolve icons from multiple sources. The example shows a local registry for assets/icons and a custom registry; the chain tries each registry in order and throws IconNotFoundException if not found.

```php
use Symfony\UX\Icons\Registry\ChainIconRegistry;
use Symfony\UX\Icons\Registry\LocalSvgIconRegistry;

$factory = new \Symfony\UX\Icons\IconFactory();
$local   = new LocalSvgIconRegistry($factory, __DIR__.'/assets/icons', [
    'flags' => __DIR__.'/assets/images/flags',
]);

$chain = new ChainIconRegistry([$local, /* your custom registry implementing IconRegistryInterface */]);

try {
    $icon = $chain->get('flags:fr'); // reads assets/images/flags/fr.svg
} catch (\Symfony\UX\Icons\Exception\IconNotFoundException $e) {
    // "Icon \"flags:fr\" not found." (+ the last registry's message)
}
```

--------------------------------

### Install symfony/http-client for icon downloads

Source: https://github.com/symfony/ux-icons/blob/3.x/doc/index.rst

Required to automatically download icons from icon sets. Without this package, UX Icons cannot fetch icons from remote sources.

```terminal
$ composer require symfony/http-client
```

--------------------------------

### Twig Component Usage Examples

Source: https://github.com/symfony/ux-icons/blob/3.x/_autodocs/api-reference/twig.md

Examples of using the <twig:ux:icon> tag in Twig templates with name and class attributes.

```html+twig
<twig:ux:icon name="user-profile" class="w-4 h-4" />
<twig:ux:icon name="mdi:check" aria-hidden="false" />
```

--------------------------------

### Configure suffix-based icon attributes for heroicons

Source: https://github.com/symfony/ux-icons/blob/3.x/doc/index.rst

Configure suffix-based attributes for the heroicons set. Icons with suffixes like 16-solid, 20-solid, or solid get fill="currentColor"; icons without a matching suffix fall back to the empty string suffix and get stroke="currentColor", stroke-width="1.5", and fill="none". All icons also receive data-slot="icon" from icon_attributes.

```yaml
# config/packages/ux_icons.yaml
ux_icons:
    icon_sets:
        heroicons:
            icon_attributes:
                data-slot: 'icon'
            suffixes:
                16-solid:
                    icon_attributes:
                        fill: 'currentColor'
                20-solid:
                    icon_attributes:
                        fill: 'currentColor'
                solid:
                    icon_attributes:
                        fill: 'currentColor'
                '':
                    icon_attributes:
                        stroke: 'currentColor'
                        stroke-width: 1.5
                        fill: 'none'
```

--------------------------------

### HttpClientNotInstalledException class definition

Source: https://github.com/symfony/ux-icons/blob/3.x/_autodocs/errors.md

Defines the exception thrown when symfony/http-client is not installed and Iconify::http() is invoked. Through the bundle's on-demand registry it is converted into an IconNotFoundException.

```php
final class HttpClientNotInstalledException extends \LogicException
{
}
```

--------------------------------

### GET /search?query={q}&prefix={prefix}

Source: https://github.com/symfony/ux-icons/blob/3.x/_autodocs/endpoints.md

Searches for icons within a given icon set on iconify.design. Used by `Iconify::searchIcons(string $prefix, string $query)`. Accepts query parameters for the search term and the icon set prefix.

```APIDOC
## GET /search?query={q}&prefix={prefix}

### Description
Searches for icons within a given icon set on iconify.design. Used by `Iconify::searchIcons(string $prefix, string $query)`.

### Method
GET

### Endpoint
/search?query={q}&prefix={prefix}

### Parameters
#### Query Parameters
- **query** (string) - Required - Search term (e.g. `arrow`).
- **prefix** (string) - Required - Icon set prefix to search within.

### Request Example
GET /search?query=arrow&prefix=mdi

### Response
#### Success Response (200)
JSON object with an `icons` array of matching icon names (`string[]`). The client wraps the whole response in a `\ArrayObject`; the `ux:icons:search` command reads `$results['icons']`, sorts it, and pages it in chunks of 24.

#### Response Example
{
  "icons": ["arrow-left", "arrow-right"]
}

### Error Handling
No status-code validation is performed for this call; transport/JSON failures propagate and are caught by the command (which prints `An error occurred while searching for icons.` and exits `FAILURE`).
```

--------------------------------

### GET /{prefix}.json?icons={name1,name2,...}

Source: https://github.com/symfony/ux-icons/blob/3.x/_autodocs/endpoints.md

Fetches multiple icons from a given icon set on iconify.design. Used by `Iconify::fetchIcons(string $prefix, array $names)`. Accepts a path parameter for the icon set prefix and a query parameter for a comma-separated list of icon names.

```APIDOC
## GET /{prefix}.json?icons={name1,name2,...}

### Description
Fetches multiple icons from a given icon set on iconify.design. Used by `Iconify::fetchIcons(string $prefix, array $names)`.

### Method
GET

### Endpoint
/{prefix}.json?icons={name1,name2,...}

### Parameters
#### Path Parameters
- **prefix** (string) - Required - Icon set prefix.

#### Query Parameters
- **icons** (string) - Required - Comma-separated, **sorted** (to enforce cache hits) and **lowercased** icon names. Must match `#^[a-z0-9-,]+$#`; `strlen($prefix) + strlen(names)` must be ≤ 400 chars.

### Request Example
GET /{prefix}.json?icons=name1,name2

### Response
#### Success Response (200)
Response schema is the same as the single-icon variant.

#### Response Example
(Not provided in source)

### Error Handling
- non-200 or unknown set → `IconNotFoundException` (`The icon set "%s" does not exist on iconify.design.`);
- icons missing from the response or with malformed bodies are **skipped silently** — the returned `array<string, Icon>` simply has fewer entries, keyed by the original (unsorted) names;
- `\InvalidArgumentException` for an invalid query charset (`Invalid icon names.`) or an over-long query (`The query string is too long.`).
```

--------------------------------

### GET /{prefix}.json?icons={name}

Source: https://github.com/symfony/ux-icons/blob/3.x/_autodocs/endpoints.md

Fetches a single icon from the Iconify API. Used by `Iconify::fetchIcon(string $prefix, string $name)`. Returns the icon body and aliases, with error handling converting all failures to `IconNotFoundException`.

```APIDOC
## GET /{prefix}.json?icons={name}

### Description
Fetches a single icon from the Iconify API. Used by `Iconify::fetchIcon(string $prefix, string $name)`.

### Method
GET

### Endpoint
/{prefix}.json?icons={name}

### Parameters
#### Path Parameters
- **prefix** (string) - Required - Icon set prefix, e.g. `mdi`. Must exist in the `/collections` metadata, else `IconNotFoundException`.

#### Query Parameters
- **icons** (string) - Required - Single icon name, e.g. `check`.

### Response
#### Success Response (200)
- **icons** (object<name, {body: string, height?: number, width?: number}>) - Icon bodies (SVG inner markup) keyed by canonical name
- **aliases** (object<name, {parent: string}>) - Alias names mapped to their parent icon

#### Response Example
{
  "icons": {
    "check": {
      "body": "<path d=\"M9 16.17L4.83 12l-1.42 1.41L9 19 21 7l-1.41-1.41z\"/>",
      "height": 24,
      "width": 24
    }
  },
  "aliases": {}
}

### Error Handling
All errors are converted to `IconNotFoundException` (see [errors.md](errors.md)):
- non-200 — `The icon "%s:%s" does not exist on iconify.design.`
- 200 with non-JSON body — `JsonException` caught, same message
- 200 with JSON but no `icons[name].body` (or `aliases[name].parent` target missing) — same message
- body that fails SVG parsing — wrapped as `The icon "%s:%s" from iconify.design is not a valid SVG.` with the original exception as `previous`

### Response Processing
If `aliases[name]` exists, `parent` is used as the canonical name; height/width resolve per-icon → response-level → set-level → `16`; the resulting `Icon` is created with attributes `xmlns = http://www.w3.org/2000/svg` and `viewBox = "0 0 {w} {h}"`.
```

--------------------------------

### ChainIconRegistry get() exception when all registries fail

Source: https://github.com/symfony/ux-icons/blob/3.x/_autodocs/api-reference/registries.md

Throws an IconNotFoundException when no registry returns an icon. The message includes the icon name and the last exception message, with the previous exception passed as the previous parameter.

```php
throw new IconNotFoundException(
    sprintf('Icon "%s" not found.', $name) . ' ' . $e->getMessage(),
    previous: $e ?? null,
);
```

--------------------------------

### Render icons with twig:ux:icon HTML component

Source: https://github.com/symfony/ux-icons/blob/3.x/doc/index.rst

Equivalent HTML syntax for rendering icons when symfony/ux-twig-component is installed. Uses the same attributes as the Twig function.

```html+twig
<twig:ux:icon name="user-profile" class="w-4 h-4" />
<twig:ux:icon name="mdi:home" class="w-4 h-4" />
```

--------------------------------

### IconCacheWarmer::warm method

Source: https://github.com/symfony/ux-icons/blob/3.x/_autodocs/api-reference/bundle.md

Defines the warm method that accepts optional success and failure callbacks. For each icon name from IconFinder::icons(), it calls $registry->get($name, refresh: true) and then dispatches to the callbacks. Invalid names throw IconNotFoundException.

```php
/**
 * @param callable(string,Icon):void|null       $onSuccess
 * @param callable(string,\Exception):void|null $onFailure
 */
public function warm(?callable $onSuccess = null, ?callable $onFailure = null): void
```

--------------------------------

### Search icon sets with ux:icons:search

Source: https://github.com/symfony/ux-icons/blob/3.x/doc/index.rst

Searches for an icon set by name and shows its details (icon count, license, prefix, example). The output includes a prompt to search for 'arrow' in Tabler Icons, which is the next command.

```terminal
$ php bin/console ux:icons:search tabler
```

```terminal
 -------------- ------- --------- -------- --------------
  Icon set       Icons   License   Prefix   Example
 -------------- ------- --------- -------- --------------
  Tabler Icons    5219   MIT       tabler   tabler:alien
 -------------- ------- --------- -------- --------------

 Search "arrow" in Tabler Icons icons:

  php bin/console ux:icons:search tabler arrow
```

--------------------------------

### Auto-lock on-demand icons with ux_icons.iconify.auto_lock

Source: https://github.com/symfony/ux-icons/blob/3.x/_autodocs/api-reference/registries.md

When auto_lock is enabled, the first render of an on-demand icon downloads it and persists it to assets/icons/, so subsequent requests and production use the local file. The example shows the Twig template usage and the resulting behavior.

```php
// with ux_icons.iconify.auto_lock: true, the first render of an on-demand icon
// persists it to assets/icons/, so subsequent requests (and production) read it locally:

// {{ ux_icon('flowbite:user-solid') }}
// → downloads once, writes assets/icons/flowbite/user-solid.svg, then serves the local file
```

--------------------------------

### Icon caching with ux_icon() in Twig

Source: https://github.com/symfony/ux-icons/blob/3.x/doc/index.rst

Shows which icon usages are cached: string literals are cached, dynamically built names are not. The example demonstrates that a variable map of icon names will be cached because the names are literal strings.

```twig
{# This will be cached #}
{{ ux_icon('flag-fr') }}

{# This will NOT be cached #}
{{ ux_icon('flag-' ~ locale) }}

{# in this example, both "flag-fr" and "flag-de" will be cached #}
{% set flags = {fr: 'flag-fr', de: 'flag-de'} %}
{{ ux_icon(flags[locale]) }}
```

--------------------------------

### Fetch an icon on demand with Iconify

Source: https://github.com/symfony/ux-icons/blob/3.x/_autodocs/api-reference/iconify.md

Demonstrates how to instantiate the Iconify service, check for icon set existence, fetch a specific icon, and retrieve metadata for a set.

```php
use Symfony\UX\Icons\Exception\IconNotFoundException;
use Symfony\UX\Icons\IconFactory;
use Symfony\UX\Icons\Iconify;
use Symfony\Contracts\Cache\CacheInterface;

$iconify = new Iconify($cache /* CacheInterface */, new IconFactory());

if (!$iconify->hasIconSet('mdi')) {
    // prefix not found in the collections metadata
}

$icon = $iconify->fetchIcon('mdi', 'check');
echo $icon->toHtml();
// <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">...</svg>

$metadata = $iconify->metadataFor('mdi');
echo $metadata['license']['title']; // Apache 2.0
```

--------------------------------

### Direct usage of Iconify service

Source: https://github.com/symfony/ux-icons/blob/3.x/_autodocs/endpoints.md

Demonstrates how to instantiate the Iconify service using a cache interface and icon factory, then perform various operations like fetching and searching icons.

```php
use Symfony\UX\Icons\IconFactory;
use Symfony\UX\Icons\Iconify;
use Symfony\Contracts\Cache\CacheInterface;

/** @var CacheInterface $cache */
$iconify = new Iconify($cache, new IconFactory());

$sets    = $iconify->getIconSets();       // GET /collections (cached)
$icon    = $iconify->fetchIcon('tabler', 'arrow-right');   // GET /tabler.json?icons=arrow-right
$icons   = $iconify->fetchIcons('tabler', ['home', 'star']); // GET /tabler.json?icons=home,star
$results = $iconify->searchIcons('tabler', 'arrow');       // GET /search?query=arrow&prefix=tabler
```

--------------------------------

### Basic Icon construction and rendering

Source: https://github.com/symfony/ux-icons/blob/3.x/_autodocs/api-reference/icon.md

Creates an Icon instance with an SVG path and attributes, then renders the full SVG markup via toHtml() and the inner SVG content via getInnerSvg(). The output comments show the expected results.

```php
use Symfony\UX\Icons\Icon;

$icon = new Icon('<path d="M21 7L9 19l-5.5-5.5l1.41-1.41L9 16.17L19.59 5.59z"/>', [
    'viewBox' => '0 0 24 24',
    'fill' => 'currentColor',
]);

echo $icon->toHtml();
// <svg viewBox="0 0 24 24" fill="currentColor"><path d="..."/></svg>

echo $icon->getInnerSvg();
// <path d="M21 7L9 19l-5.5-5.5l1.41-1.41L9 16.17L19.59 5.59z"/>
```

--------------------------------

### Render icons with aliases and per-set attributes

Source: https://github.com/symfony/ux-icons/blob/3.x/_autodocs/api-reference/icon-renderer.md

Demonstrates renderIcon() calls with the given configuration. Shows how aliases, per-set attributes, suffix-specific attributes, and default attributes are applied.

```php
$this->iconRenderer->renderIcon('dots');
// resolves alias -> "clarity:ellipsis-horizontal-line" -> set "clarity" attributes + svg

$this->iconRenderer->renderIcon('heroicons:arrow-right-solid', ['class' => 'size-4']);
// attributes: data-slot="icon" (set) + fill="currentColor" (suffix "solid") + class="size-4" (invocation)

$this->iconRenderer->renderIcon('heroicons:arrow-right');
// attributes: data-slot="icon" (set) + stroke="currentColor" fill="none" (empty suffix fallback)

$this->iconRenderer->renderIcon('check');
// no colon, no alias -> only default attributes + aria-hidden="true"
```

--------------------------------

### Import single icon with output

Source: https://github.com/symfony/ux-icons/blob/3.x/_autodocs/api-reference/commands.md

Shows the output when importing a single icon. The command prints the icon set and license, a success marker for each imported icon, and a summary line.

```bash
php bin/console ux:icons:import mdi:home
#  Icon set: Material Design Icons (License: Apache 2.0)
#   ✓ Imported mdi:home
#  [OK] Imported 1/1 icons.
```

--------------------------------

### Full ux_icons.yaml configuration

Source: https://github.com/symfony/ux-icons/blob/3.x/_autodocs/configuration.md

This configuration file defines the local icon directory, default attributes, icon aliases, Iconify settings, and specific icon set configurations.

```yaml
# config/packages/ux_icons.yaml
ux_icons:
    # The local directory where icons are stored
    icon_dir: '%kernel.project_dir%/assets/icons'

    # Default attributes to add to all icons
    default_icon_attributes:
        fill: currentColor
        'font-size': '1.25em'

    # Icon aliases (alias => icon name)
    aliases:
        dots: 'clarity:ellipsis-horizontal-line'
        'tabler:save': 'tabler:device-floppy'

    # Configuration for the "on demand" icons powered by Iconify.design
    iconify:
        enabled: true
        on_demand: true
        auto_lock: false
        endpoint: 'https://api.iconify.design'

    # Whether to ignore errors when an icon is not found
    ignore_not_found: false

    # Icon sets configuration, array of prefix => icon set configuration
    icon_sets:
        flags:
            # Either map to a local directory...
            path: '%kernel.project_dir%/assets/images/flags'
            # ... or to an existing icon set identifier (mutually exclusive)
            # alias: 'lucide'

            # Override default_icon_attributes for this set
            icon_attributes:
                class: 'flag'
                stroke: 'none'
                fill: false   # `false` removes a default attribute

            # Suffix-based attributes
            suffixes:
                '16-solid':
                    icon_attributes:
                        fill: 'currentColor'
                '20-solid':
                    icon_attributes:
                        fill: 'currentColor'
                solid:
                    icon_attributes:
                        fill: 'currentColor'
                '':
                    icon_attributes:
                        stroke: 'currentColor'
                        stroke-width: 1.5
                        fill: 'none'
```

--------------------------------

### Full Icon Management Pipeline

Source: https://github.com/symfony/ux-icons/blob/3.x/_autodocs/api-reference/commands.md

A sequence of commands to search for icons, import them as local files, lock referenced icons, and warm the cache.

```bash
# 1) find an icon set and icons
php bin/console ux:icons:search tabler arrow

# 2) import the ones you need (they become committed local files)
php bin/console ux:icons:import tabler:arrow-right tabler:arrow-left

# 3) alternatively: lock every on-demand icon referenced in your templates
php bin/console ux:icons:lock

# 4) warm the icon cache in production
php bin/console ux:icons:warm-cache
```

--------------------------------

### IconRegistryInterface definition

Source: https://github.com/symfony/ux-icons/blob/3.x/_autodocs/types.md

Defines the IconRegistryInterface in the Symfony\UX\Icons namespace. It extends \IteratorAggregate<string> and is marked @internal. The get method throws IconNotFoundException when an icon is not found. Consumers include IconRenderer, CacheIconRegistry, ChainIconRegistry, and AutoLockIconRegistry.

```php
/**
 * @extends \IteratorAggregate<string>
 *
 * @internal
 */
interface IconRegistryInterface
{
    /**
     * @throws IconNotFoundException
     */
    public function get(string $name): Icon;
}
```

--------------------------------

### UXIconsBundle class

Source: https://github.com/symfony/ux-icons/blob/3.x/_autodocs/api-reference/bundle.md

The bundle class for UXIcons, with a getPath() method returning the bundle directory.

```php
final class UXIconsBundle extends Bundle
{
    public function getPath(): string
    {
        return \dirname(__DIR__);
    }
}
```

--------------------------------

### Load a local icon file

Source: https://github.com/symfony/ux-icons/blob/3.x/_autodocs/api-reference/icon-factory.md

Instantiate an IconFactory and load an SVG icon from a local file path.

```php
use Symfony\UX\Icons\IconFactory;

$factory = new IconFactory();

$icon = $factory->fromFile(__DIR__.'/assets/icons/menu.svg');
echo $icon->toHtml();
// <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">...</svg>
```

--------------------------------

### Batch fetch icons with chunking and error handling

Source: https://github.com/symfony/ux-icons/blob/3.x/_autodocs/api-reference/iconify.md

Shows how to use the chunk() method to process large lists of icon names in batches, with error handling for invalid names or query length issues.

```php
use Symfony\UX\Icons\Iconify;

$iconify = new Iconify($cache, new IconFactory(), endpoint: 'https://api.iconify.design');

$names = ['home', 'user-solid', 'star', 'invalid@name'];
try {
    // chunk() splits the list into URL-safe batches
    foreach ($iconify->chunk('flowbite', $names) as $batch) {
        $icons = $iconify->fetchIcons('flowbite', $batch);
        foreach ($icons as $name => $icon) {
            // $name is the original casing; missing/malformed icons are simply absent
        }
    }
} catch (\InvalidArgumentException $e) {
    // invalid name characters or query too long
}
```

--------------------------------

### Run ux:icons:warm-cache in Production

Source: https://github.com/symfony/ux-icons/blob/3.x/_autodocs/api-reference/commands.md

Execute the cache warming command in a production environment, typically before receiving traffic.

```bash
# in production, before traffic
php bin/console ux:icons:warm-cache -v
```

--------------------------------

### ux:icons:import command class

Source: https://github.com/symfony/ux-icons/blob/3.x/_autodocs/api-reference/commands.md

Defines the ux:icons:import console command. The constructor injects Iconify and LocalSvgIconRegistry. The command imports icons from iconify.design.

```php
#[AsCommand(
    name: 'ux:icons:import',
    description: 'Import icon(s) from iconify.design',
)]
final class ImportIconCommand extends Command
{
    public function __construct(private Iconify $iconify, private LocalSvgIconRegistry $registry)
}
```

--------------------------------

### IconifyOnDemandRegistry class constructor

Source: https://github.com/symfony/ux-icons/blob/3.x/_autodocs/api-reference/registries.md

Defines the IconifyOnDemandRegistry class implementing IconRegistryInterface. The constructor accepts an Iconify client and an optional array of prefix aliases mapping local prefixes to remote Iconify prefixes (config: icon_sets.<prefix>.alias).

```php
final class IconifyOnDemandRegistry implements IconRegistryInterface
{
    public function __construct(
        private Iconify $iconify,
        private ?array $prefixAliases = [],
    )
}
```

--------------------------------

### Render icons with IconRendererInterface

Source: https://github.com/symfony/ux-icons/blob/3.x/_autodocs/api-reference/icon-renderer.md

Shows how to inject IconRendererInterface via autowiring and render icons with renderIcon(). The first call uses the default icons directory, the second specifies the 'lucide' set and passes extra attributes.

```php
use Symfony\UX\Icons\IconRendererInterface;

// injected via autowiring (the bundle aliases the interface)
final class SomeService
{
    public function __construct(private IconRendererInterface $iconRenderer)
    {
    }

    public function headerIcon(): string
    {
        // icon from the default icons directory
        return $this->iconRenderer->renderIcon('arrow-right');

        // icon from the "lucide" set, with extra attributes
        return $this->iconRenderer->renderIcon('lucide:heart', ['class' => 'color-red']);
    }
}
```

--------------------------------

### UXIconsExtension class

Source: https://github.com/symfony/ux-icons/blob/3.x/_autodocs/api-reference/bundle.md

The extension class for the ux_icons configuration namespace, implementing ConfigurationInterface.

```php
final class UXIconsExtension extends ConfigurableExtension implements ConfigurationInterface
{
    public function getConfigTreeBuilder(): TreeBuilder
    public function getConfiguration(array $config, ContainerBuilder $container): ConfigurationInterface
    protected function loadInternal(array $mergedConfig, ContainerBuilder $container): void
}
```

--------------------------------

### IconCacheWarmer::__construct

Source: https://github.com/symfony/ux-icons/blob/3.x/_autodocs/api-reference/bundle.md

Creates a new IconCacheWarmer instance with a cache-backed registry and an icon finder.

```APIDOC
## IconCacheWarmer::__construct

### Description
Creates a new IconCacheWarmer instance with the given cache-backed registry and icon finder.

### Method
Constructor

### Signature
```php
public function __construct(private CacheIconRegistry $registry, private IconFinder $icons)
```

### Parameters
- `$registry` (CacheIconRegistry) - Required - The cache-backed registry; `refresh: true` forces recomputation.
- `$icons` (IconFinder) - Required - Finds icon names in Twig templates and the icon directory.

```

--------------------------------

### Import multiple icons with ux:icons:import

Source: https://github.com/symfony/ux-icons/blob/3.x/_autodocs/api-reference/commands.md

Imports two icons in a single invocation. The command accepts multiple icon names as arguments.

```bash
# import two icons (flowbite:user-solid and flowbite:home-solid)
php bin/console ux:icons:import flowbite:user-solid flowbite:home-solid
```

--------------------------------

### Set icon size with CSS framework utilities

Source: https://github.com/symfony/ux-icons/blob/3.x/doc/index.rst

Use sizing utilities from CSS frameworks like Tailwind or Bootstrap for consistency and theming.

```html+twig
{# Twig function #}
{{ ux_icon('bi:chat', {class: 'size-4'}) }}

{# HTML syntax #}
<twig:ux:icon name="bi:chat" class="size-4" />
```

--------------------------------

### Importing Icons via CLI

Source: https://github.com/symfony/ux-icons/blob/3.x/doc/index.rst

Commands to download specific icons into the assets/icons/ directory for local locking.

```terminal
# icon will be saved in `assets/icons/flowbite/user-solid.svg` and you can
# use it with the name: `flowbite:user-solid`
$ php bin/console ux:icons:import flowbite:user-solid

# it's also possible to import several icons at once
$ php bin/console ux:icons:import flowbite:user-solid flowbite:home-solid
```

--------------------------------

### UXIconRuntime::render() - component renderer entry point

Source: https://github.com/symfony/ux-icons/blob/3.x/_autodocs/api-reference/twig.md

Signature of the render() method, the entry point for the Twig component renderer. It extracts the 'name' key from $args and passes the remaining keys as attributes to renderIcon().

```php
public function render(array $args = []): string
```

--------------------------------

### Build an icon from a raw body and handle errors

Source: https://github.com/symfony/ux-icons/blob/3.x/_autodocs/api-reference/icon-factory.md

Create an icon from a raw SVG string while stripping unsafe elements, and handle potential RuntimeExceptions for malformed input.

```php
use Symfony\UX\Icons\IconFactory;

$factory = new IconFactory();

// body from an untrusted source: scripts/handlers are stripped
$icon = $factory->fromBody('<path d="M3 12h18" onclick="alert(1)"/>', [
    'xmlns' => IconFactory::SVG_NAMESPACE,
    'viewBox' => '0 0 24 24',
]);
echo $icon->toHtml();
// <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M3 12h18"/></svg>

// malformed bodies raise a RuntimeException
try {
    $factory->fromBody('<svg><unknown');
} catch (\RuntimeException $e) {
    echo $e->getMessage(); // The icon body is not valid SVG.
}
```

--------------------------------

### UXIconRuntime::__construct() - constructor with ignoreNotFound and logger

Source: https://github.com/symfony/ux-icons/blob/3.x/_autodocs/api-reference/twig.md

Constructor for UXIconRuntime. The $ignoreNotFound parameter (config: ignore_not_found) controls whether missing icons render as an empty string instead of throwing; when true, a warning is logged via the optional PSR-3 logger.

```php
final class UXIconRuntime implements RuntimeExtensionInterface
{
    public function __construct(
        private readonly IconRendererInterface $iconRenderer,
        private readonly bool $ignoreNotFound = false,
        private readonly ?LoggerInterface $logger = null,
    )
}
```

--------------------------------

### LocalSvgIconRegistry::add method

Source: https://github.com/symfony/ux-icons/blob/3.x/_autodocs/api-reference/registries.md

Persists an SVG icon to the filesystem.

```php
public function add(string $name, string $svg): void
```

--------------------------------

### IconRenderer constructor with docblock

Source: https://github.com/symfony/ux-icons/blob/3.x/_autodocs/api-reference/icon-renderer.md

Constructor for IconRenderer. Accepts the icon registry and optional arrays for default attributes, aliases, per-set attributes, and per-set suffix attributes. The registry is required; all other parameters default to empty arrays.

```php
/**
 * @param array<string, mixed>                               $defaultIconAttributes
 * @param array<string, string>                              $iconAliases
 * @param array<string, array<string, mixed>>                $iconSetsAttributes
 * @param array<string, array<string, array<string, mixed>>> $iconSuffixAttributes
 */
public function __construct(
    private readonly IconRegistryInterface $registry,
    private readonly array $defaultIconAttributes = [],
    private readonly array $iconAliases = [],
    private readonly array $iconSetsAttributes = [],
    private readonly array $iconSuffixAttributes = [],
)
```

--------------------------------

### Use <twig:ux:icon> HTML syntax

Source: https://github.com/symfony/ux-icons/blob/3.x/doc/index.rst

Demonstrates the HTML-based syntax for including icons. The name attribute can reference a local icon, a sub-directory icon, or a remote icon set, and any HTML attributes can be added.

```html+twig
{# renders "user-profile.svg" #}
<twig:ux:icon name="user-profile" class="w-4 h-4" />

{# renders "admin/user-profile.svg", stored in a sub-directory #}
<twig:ux:icon name="admin:user-profile" class="w-4 h-4" />

{# renders "user-solid.svg" from the "Flowbite" icon set via ux.symfony.com #}
<twig:ux:icon name="flowbite:user-solid" />

{# you can also add any HTML attributes #}
<twig:ux:icon name="user-profile" height="16" width="16" aria-hidden="true" />
```

--------------------------------

### Iconify constructor

Source: https://github.com/symfony/ux-icons/blob/3.x/_autodocs/api-reference/iconify.md

Constructor for the Iconify class. Accepts a cache pool, an IconFactory, an optional endpoint, an optional HTTP client, and an optional maximum icons query length. If no HTTP client is provided, one is created lazily with HttpClient::create() and scoped to the endpoint.

```php
public function __construct(
    private CacheInterface $cache,
    private IconFactory $iconFactory,
    private string $endpoint = self::API_ENDPOINT,
    private ?HttpClientInterface $httpClient = null,
    ?int $maxIconsQueryLength = null,
)
```

--------------------------------

### toHtml(): string

Source: https://github.com/symfony/ux-icons/blob/3.x/_autodocs/api-reference/icon.md

Serializes the icon to a full <svg> element. Each attribute is rendered according to its value type.

```APIDOC
## toHtml(): string

### Description
Serializes the icon to a full `<svg>` element. Each attribute is rendered according to its value type.

### Method
`toHtml(): string`

### Returns
- **string** - The complete `<svg ...>...</svg>` HTML string.

### Attribute Rendering Rules
| Attribute value | Output |
|-----------------|--------|
| `false` | attribute omitted entirely (acts as removal) |
| `true` (boolean) | attribute name only, no value (`aria-hidden`) |
| `true` for an `aria-*` attribute | attribute name with value `"true"` (per WAI-ARIA 1.1 states/properties) |
| `string` / `int` / `float` | `name="value"`, escaped with `htmlspecialchars($value, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8')` |
```

--------------------------------

### Manually warm icon cache with IconCacheWarmer

Source: https://github.com/symfony/ux-icons/blob/3.x/_autodocs/api-reference/bundle.md

Retrieve the '.ux_icons.cache_warmer' service from the container and call warm() with onSuccess and onFailure callbacks. The callbacks print the icon name and, on failure, the exception message.

```php
use Symfony\UX\Icons\IconCacheWarmer;

$warmer = $container->get('.ux_icons.cache_warmer');

$warmer->warm(
    onSuccess: static fn (string $name, $icon) => printf("cached %s\n", $name),
    onFailure: static fn (string $name, \Exception $e) => printf("failed %s: %s\n", $name, $e->getMessage()),
);
```

--------------------------------

### Debug Symfony UX Icons configuration

Source: https://github.com/symfony/ux-icons/blob/3.x/_autodocs/configuration.md

Use these console commands to inspect the default configuration values or the actual configuration currently applied to your application.

```bash
# Displays the default config values
php bin/console config:dump-reference ux_icons

# Displays the actual config values used by your application
php bin/console debug:config ux_icons
```

--------------------------------

### Configure ignore_not_found for missing icons

Source: https://github.com/symfony/ux-icons/blob/3.x/_autodocs/api-reference/twig.md

Configures the ux_icons bundle to ignore missing icons in production, preventing IconNotFoundException errors.

```yaml
# config/packages/ux_icons.yaml
ux_icons:
    ignore_not_found: true
```

--------------------------------

### Configure ux_icons in config/packages/ux_icons.yaml

Source: https://github.com/symfony/ux-icons/blob/3.x/doc/index.rst

Configuration file for the UX Icons component. All options are set under the ux_icons key in your application configuration.

```yaml
# config/packages/ux_icons.yaml
ux_icons:
    {# ... #}
```

--------------------------------

### withAttributes method

Source: https://github.com/symfony/ux-icons/blob/3.x/_autodocs/api-reference/icon.md

Returns a new Icon instance with merged attributes. Pass false as a value to remove an attribute.

```php
/**
 * @param array<string, string|bool|int|float> $attributes
 */
public function withAttributes(array $attributes): self
```

--------------------------------

### Command class for ux:icons:search

Source: https://github.com/symfony/ux-icons/blob/3.x/_autodocs/api-reference/commands.md

Defines the console command class for ux:icons:search. The constructor injects the Iconify service. The command's behavior is described in the surrounding documentation: it searches icon sets or icons, handles interactive prompts, and returns exit codes SUCCESS (0), INVALID (2), or FAILURE (1).

```php
#[AsCommand(
    name: 'ux:icons:search',
    description: 'Search icons and icon sets from ux.symfony.com',
)]
final class SearchIconCommand extends Command
{
    public function __construct(private Iconify $iconify)
}
```

--------------------------------

### IconFinder icons() Method

Source: https://github.com/symfony/ux-icons/blob/3.x/_autodocs/api-reference/twig.md

Method signature for retrieving the list of available icon names.

```php
/**
 * @return string[]
 */
public function icons(): array
```

--------------------------------

### Enabling Auto-Lock Configuration

Source: https://github.com/symfony/ux-icons/blob/3.x/doc/index.rst

Configuration to automatically lock on-demand icons upon first render in development.

```yaml
# config/packages/ux_icons.yaml
when@dev:
    ux_icons:
        iconify:
            auto_lock: true
```

--------------------------------

### __toString(): string

Source: https://github.com/symfony/ux-icons/blob/3.x/_autodocs/api-reference/icon.md

Alias of toHtml() (the class implements \Stringable).

```APIDOC
## __toString(): string

### Description
Alias of `toHtml()` (the class implements `\Stringable`).

### Method
`__toString(): string`

### Returns
- **string** - The complete `<svg ...>...</svg>` HTML string.
```

--------------------------------

### Render icons with Twig function and component

Source: https://github.com/symfony/ux-icons/blob/3.x/README.md

Demonstrates how to render an icon using the ux_icon Twig function or the twig:ux:icon component, along with the resulting SVG output.

```twig
{# Twig function.. #}
{{ ux_icon('mdi:check', {class: 'w-4 h-4'}) }}

{# .. or Twig Component #}
<twig:ux:icon name="mdi:check" class="w-4 h-4" />

{# Render the "check" icon from "mdi" pack with class #}
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor" class="w-4 h-4">
    <path d="M21 7L9 19l-5.5-5.5l1.41-1.41L9 16.17L19.59 5.59z"/>
</svg>
```

--------------------------------

### Search icons and icon sets with ux:icons:search

Source: https://github.com/symfony/ux-icons/blob/3.x/_autodocs/api-reference/commands.md

Search for icon sets or icons. The first command lists icon sets matching 'tabler'; the second searches for icons named 'arrow' in the 'tabler' set. Both are run from the project root.

```bash
php bin/console ux:icons:search tabler
```

```bash
php bin/console ux:icons:search tabler arrow
```

--------------------------------

### ChainIconRegistry class constructor

Source: https://github.com/symfony/ux-icons/blob/3.x/_autodocs/api-reference/registries.md

Defines the ChainIconRegistry class implementing IconRegistryInterface. The constructor accepts an iterable of IconRegistryInterface instances, which in the bundle is a tagged_iterator('ux_icons.registry') sorted by tag priority.

```php
final class ChainIconRegistry implements IconRegistryInterface
{
    /**
     * @param IconRegistryInterface[] $registries
     */
    public function __construct(private iterable $registries)
}
```

--------------------------------

### Local Icon Directory Structure

Source: https://github.com/symfony/ux-icons/blob/3.x/doc/index.rst

The directory structure for storing local SVG icons in the assets/icons/ folder.

```text
your-project/
├─ assets/
│  └─ icons/
│     ├─ bi/
│     │  └─ pause-circle.svg
│     │  └─ play-circle.svg
│     ├─ header/
│     │  ├─ logo.svg
│     │  └─ menu.svg
│     ├─ close.svg
│     ├─ menu.svg
│     └─ ...
└─ ...
```

--------------------------------

### Configure aliases and per-set attributes

Source: https://github.com/symfony/ux-icons/blob/3.x/_autodocs/api-reference/icon-renderer.md

Configuration for aliases and per-set attributes. Defines an alias 'dots' and sets default attributes for the 'heroicons' set, including suffix-specific attributes for 'solid' and empty suffix.

```yaml
ux_icons:
    aliases:
        dots: 'clarity:ellipsis-horizontal-line'
    icon_sets:
        heroicons:
            icon_attributes:
                data-slot: 'icon'
            suffixes:
                solid:
                    icon_attributes:
                        fill: 'currentColor'
                '':
                    icon_attributes:
                        stroke: 'currentColor'
                        fill: 'none'
```

--------------------------------

### LocalSvgIconRegistry::has method

Source: https://github.com/symfony/ux-icons/blob/3.x/_autodocs/api-reference/registries.md

Checks if an icon exists by attempting to retrieve it.

```php
public function has(string $name): bool
```

--------------------------------

### ChainIconRegistry::get

Source: https://github.com/symfony/ux-icons/blob/3.x/_autodocs/api-reference/registries.md

Retrieves an icon by name, trying each registered registry in order. The first registry that returns an icon wins; failures are swallowed and the next registry is tried.

```APIDOC
## ChainIconRegistry::get

### Description
Retrieves an icon by name, trying each registered registry in order. The first registry that returns an icon wins; failures are swallowed and the next registry is tried.

### Method
`get(string $name): Icon`

### Parameters
- **$name** (string) - Required - The icon name to look up.

### Response
Returns an `Icon` instance if found.

### Errors
Throws `IconNotFoundException` if no registry can provide the icon.
```

--------------------------------

### CacheIconRegistry class constructor

Source: https://github.com/symfony/ux-icons/blob/3.x/_autodocs/api-reference/registries.md

Defines the CacheIconRegistry class implementing IconRegistryInterface. The constructor accepts an inner IconRegistryInterface (the chain) and a CacheInterface for caching parsed Icon instances.

```php
final class CacheIconRegistry implements IconRegistryInterface
{
    public function __construct(private IconRegistryInterface $inner, private CacheInterface $cache)
}
```

--------------------------------

### toHtml method

Source: https://github.com/symfony/ux-icons/blob/3.x/_autodocs/api-reference/icon.md

Serializes the icon to a full <svg> element.

```php
public function toHtml(): string
```

--------------------------------

### AutoLockIconRegistry class constructor

Source: https://github.com/symfony/ux-icons/blob/3.x/_autodocs/api-reference/registries.md

Defines the AutoLockIconRegistry class implementing IconRegistryInterface. The constructor takes an inner registry, a local SVG registry for persistence, and an optional PSR-3 logger. It decorates the on-demand registry to persist icons to disk on first render (config: iconify.auto_lock).

```php
final class AutoLockIconRegistry implements IconRegistryInterface
{
    public function __construct(
        private readonly IconRegistryInterface $inner,
        private readonly LocalSvgIconRegistry $localRegistry,
        private readonly ?LoggerInterface $logger = null,
    )
}
```

--------------------------------

### LocalSvgIconRegistry

Source: https://github.com/symfony/ux-icons/blob/3.x/_autodocs/api-reference/registries.md

Registry that resolves and stores SVG icons on the local filesystem.

```APIDOC
## LocalSvgIconRegistry

### Description
Registry that resolves and stores SVG icons on the local filesystem.

### Constructor

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `$iconFactory` | `IconFactory` | yes | — | Factory used to parse/sanitize the `.svg` files. |
| `$iconDir` | `string` | yes | — | Root icons directory (config: `icon_dir`, default `%kernel.project_dir%/assets/icons`). |
| `$iconSetPaths` | `array<string, string>` | no | `[]` | Map of prefix → absolute directory for explicitly configured icon sets (config: `icon_sets.<prefix>.path`). |

### `get(string $name): Icon`

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `$name` | `string` | yes | — | Icon name. |

Resolution order:

1. If `$name` contains `:`, it is split into prefix/icon (`explode(':', $name, 2)`). An empty prefix or icon → `IconNotFoundException` (`The icon name "%s" is not valid.`).
2. If `$iconSetPaths[$prefix]` exists, the file `{$prefixPath}/{icon-with-'-'/'for-':'...}.svg` is looked up; missing → `The icon "%s" (%s) does not exist.` (message includes the attempted filename).
3. Otherwise the file `{$iconDir}/{str_replace(':', '/', $name)}.svg` is looked up; missing → same `IconNotFoundException`.

**Throws:** `IconNotFoundException` (conditions above).

### `has(string $name): bool`

**Returns:** `true` if `get($name)` succeeds, `false` if it throws `IconNotFoundException` (implemented as a try/catch around `get()`).

### `add(string $name, string $svg): void`

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `$name` | `string` | yes | — | Relative target path without the `.svg` extension, e.g. `mdi/check`. |
| `$svg` | `string` | yes | — | Full SVG markup to persist. |

Writes the file `{$iconDir}/{$name}.svg` with `new Filesystem()->dumpFile(...)`. Used by the import/lock commands and by `AutoLockIconRegistry`.
```

--------------------------------

### idToName method signature

Source: https://github.com/symfony/ux-icons/blob/3.x/_autodocs/api-reference/icon.md

Converts a valid icon ID into an icon name by replacing -- with :.

```php
public static function idToName(string $id): string
```

--------------------------------

### Runtime icon rendering data flow

Source: https://github.com/symfony/ux-icons/blob/3.x/_autodocs/api-reference/bundle.md

Shows how ux_icon() and the twig component flow from the Twig extension through the renderer and registries, ending at the local SVG registry or the on-demand/auto-lock registries that fetch from Iconify when needed.

```text
Twig: ux_icon() / <twig:ux:icon>
  -> UXIconRuntime::renderIcon() (ignore_not_found gate)
  -> IconRenderer::renderIcon()   (aliases, set/suffix attributes, aria-hidden)
  -> CacheIconRegistry::get()     (cache key Icon::nameToId(); validity check)
  -> ChainIconRegistry::get()     (try registries in priority order)
       -> LocalSvgIconRegistry (priority 10)   -> IconFactory::fromFile()
       -> AutoLockIconRegistry (priority -10)  -> IconifyOnDemandRegistry -> Iconify::fetchIcon() -> IconFactory::fromBody()
```

--------------------------------

### ux:icons:lock

Source: https://github.com/symfony/ux-icons/blob/3.x/_autodocs/api-reference/commands.md

Scan project and import icon(s) from iconify.design. The command collects icon candidates, remaps prefixes via aliases, skips already-local icons unless --force is used, and saves fetched icons to the local registry.

```APIDOC
## ux:icons:lock

### Description
Scans the project and imports icons from iconify.design. Collects candidate icon names from configured aliases and icon finder results, then downloads and saves any missing icons unless forced.

### Method
COMMAND

### Endpoint Path
`ux:icons:lock`

### Usage
```bash
php bin/console ux:icons:lock [options]
```

### Constructor Parameters
- **$iconify** (Iconify) - Required - Service: icon retrieval client.
- **$registry** (LocalSvgIconRegistry) - Required - Service: local SVG registry for storage.
- **$iconFinder** (IconFinder) - Required - Service: locates icon candidates in the project.
- **$iconAliases** (array) - Optional, default `[]` - Config key: `aliases`.
- **$iconSetAliases** (array) - Optional, default `[]` - Config key: `icon_sets.<prefix>.alias`.

### Options
- `--force` (VALUE_NONE) - Force re-import of all found icons (default: icons that already exist locally are skipped).

### Behavior
1. Collects candidate names: values of `iconAliases` followed by `IconFinder::icons()`.
2. Only candidates that split into exactly 2 parts on `:` are considered; the prefix is remapped through `iconSetAliases`.
3. Skips icons already present (`LocalSvgIconRegistry::has()`) unless `--force` is given.
4. Unknown sets are skipped (verbose `✗ IconSet Not Found`, shown with `-v`/`-vv`); `IconNotFoundException` from `fetchIcon()` is skipped (verbose `✗ Icon Not Found`, with `-v`).
5. Successful icons are persisted with `LocalSvgIconRegistry::add("$prefix/$name", $iconSvg)` and printed with license info and the `{{ ux_icon('...') }}` snippet.

### Exit Codes
- Always returns `Command::SUCCESS` (0).

### Examples
```bash
# Lock all on-demand icons found in Twig templates
php bin/console ux:icons:lock

# Re-download everything, overwriting local copies
php bin/console ux:icons:lock --force -v
```
```

--------------------------------

### Debug ux_icons configuration

Source: https://github.com/symfony/ux-icons/blob/3.x/doc/index.rst

Commands to inspect the UX Icons configuration. config:dump-reference shows defaults, debug:config shows the actual values used by your application.

```terminal
# Displays the default config values
$ php bin/console config:dump-reference ux_icons

# Displays the actual config values used by your application
$ php bin/console debug:config ux_icons
```

--------------------------------

### LocalSvgIconRegistry class definition

Source: https://github.com/symfony/ux-icons/blob/3.x/_autodocs/api-reference/registries.md

The class definition for LocalSvgIconRegistry, implementing IconRegistryInterface and defining its constructor dependencies.

```php
final class LocalSvgIconRegistry implements IconRegistryInterface
{
    /**
     * @param array<string, string> $iconSetPaths
     */
    public function __construct(
        private readonly IconFactory $iconFactory,
        private readonly string $iconDir,
        private readonly array $iconSetPaths = [],
    )
}
```

--------------------------------

### Icon constructor

Source: https://github.com/symfony/ux-icons/blob/3.x/_autodocs/api-reference/icon.md

Constructor for the Icon class. Accepts the inner SVG markup and optional HTML attributes. No validation is performed; attributes with a false value are treated as removed.

```php
public function __construct(
    private readonly string $innerSvg,
    private readonly array $attributes = [],
)
```

--------------------------------

### Serialization hooks

Source: https://github.com/symfony/ux-icons/blob/3.x/_autodocs/api-reference/icon.md

Custom serialization methods that allow Icon instances to be cached.

```php
public function __serialize(): array
public function __unserialize(array $data): void
```

--------------------------------

### __toString method

Source: https://github.com/symfony/ux-icons/blob/3.x/_autodocs/api-reference/icon.md

Alias of toHtml, allowing the class to implement Stringable.

```php
public function __toString(): string
```
Tokens:
Raw