Symfony UX Icons

Icon Names

Icons are referenced using an unique identifier that follows one of the following syntaxes:

• prefix:name (e.g. mdi:check, bi:check, editor:align-left)
• name only (e.g. check, close, menu)

The icon name is the same as the file name without the file extension (e.g. check.svg -> check).

Depending on your configuration, the prefix can be the name of an icon set, a directory where the icon is located, or a combination of both.

For example, the bi prefix refers to the Bootstrap Icons set, while the header prefix refers to the icons located in the header directory.

Icon Sets

There are many icon sets available, each with their own unique style and set of icons, providing a wide range of icons for different purposes, while maintaining a consistent look and feel across your application. Here are some of the most popular icon sets available:

To see the full list of available icon sets, visit ux.symfony.com/icons.

Search Icon sets

You can use the ux:icons:search command to search for icon sets, or to find the prefix of a specific icon set:

1
2
3
4
5
6
7
8
9
10
11

$ php bin/console ux:icons:search tabler

 -------------- ------- --------- -------- --------------
  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

Search Icons

You can also search for icons within a specific icon set. To search for "arrow" icons in the "Tabler Icons" set, use the following command:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

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

Searching Tabler Icons icons "arrow"...
Found 64 icons.
 ------------------------------------------ ------------------------------------------
  tabler:archery-arrow                       tabler:arrow-autofit-up
  tabler:arrow-back                          tabler:arrow-back-up
  tabler:arrow-badge-down                    tabler:arrow-badge-up
  tabler:arrow-badge-up-filled               tabler:arrow-bar-both
  tabler:arrow-bar-down                      tabler:arrow-bar-left
  tabler:arrow-bar-right                     tabler:arrow-bar-to-up
  tabler:arrow-bar-up                        tabler:arrow-bear-left
  tabler:arrow-big-down                      tabler:arrow-big-down-filled
  tabler:arrow-big-down-line                 tabler:arrow-big-left
  tabler:arrow-big-left-filled               tabler:arrow-big-left-line
  tabler:arrow-big-right                     tabler:arrow-big-right-filled
  tabler:arrow-big-right-line                tabler:arrow-big-up
 ------------------------------------------ ------------------------------------------

 Page 1/3. Continue? (yes/no) [yes]:
 >

HTML Syntax

In addition to the ux_icon() function explained in the previous sections, this package also supports an alternative HTML syntax based on the <twig:ux:icon> tag:

1
2
3
4
5
6
7
8
9

<!-- renders "user-profile.svg" -->
<twig:ux:icon name="user-profile" class="w-4 h-4" />
<!-- renders "admin/user-profile.svg" -->
<twig:ux:icon name="admin:user-profile" class="w-4 h-4" />
<!-- renders 'user-solid.svg' icon from '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" />

Local SVG Icons

If you already have the SVG icon files to use in your project, store them in the assets/icons/ directory and commit them. The name of the file is used as the name of the icon (icon_name.svg will be named icon_name). If located in a subdirectory, the name will be subdirectory:icon_name.

1
2
3
4
5
6
7
8
9
10
11
12
13

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

Icons On-Demand

ux.symfony.com/icons has a huge searchable repository of icons from many different sets. This package provides a way to include any icon found on this site on-demand:

1. Visit ux.symfony.com/icons and search for an icon you'd like to use. Once you find one you like, copy one of the code snippets provided.
2. Paste the snippet into your Twig template and the icon will be automatically fetched (and cached).

That's all. This works by using the Iconify API (to which ux.symfony.com/icons is a frontend for) to fetch the icon and render it in place. This icon is then cached for future requests for the same icon.

Locking On-Demand Icons

You can lock (import) all the on-demand icons you're using in your project by running the following command:

1

$ php bin/console ux:icons:lock

This command only imports icons that do not already exist locally. You can force the report to overwrite existing icons by using the --force option:

1

$ php bin/console ux:icons:lock --force

HTML Syntax

1
2
3
4
5
6
7
8
9
10

<twig:ux:icon name="user-profile" />

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

{# Renders "sub-dir/user-profile.svg" (sub-directory) #}
<twig:ux:icon name="sub-dir:user-profile" class="w-4 h-4" />

{# Renders "flowbite:user-solid" from ux.symfony.com #}
<twig:ux:icon name="flowbite:user-solid" />

Default Attributes

You can set default attributes for all icons in your configuration. These attributes will be added to all icons unless overridden by the second argument of the ux_icon function.

1
2
3
4

# config/packages/ux_icons.yaml
ux_icons:
    default_icon_attributes:
        fill: currentColor

Now, all icons will have the fill attribute set to currentColor by default.

1
2
3
4
5

# renders "user-profile.svg" with fill="currentColor"
{{ ux_icon('user-profile') }}

# renders "user-profile.svg" with fill="red"
{{ ux_icon('user-profile', {fill: 'red'}) }}

Icon Aliases

Aliases are custom names you can define to refer to any icon. They are useful for creating shortcuts to icons you frequently use in your templates:

1
2
3
4
5

# config/packages/ux_icons.yaml
ux_icons:
    # ...
    aliases:
        dots: 'clarity:ellipsis-horizontal-line'

Now, you can use the dots alias in your templates:

1
2
3
4
5
6
7
8

{{ ux_icon('dots') }}
{# with the previous configuration, this is the same as: #}
{{ ux_icon('clarity:ellipsis-horizontal-line') }}

{# using the HTML syntax #}
<twig:ux:icon name="dots" />
{# same as: #}
<twig:ux:icon name="clarity:ellipsis-horizontal-line" />

On-Demand VS Import

While on-demand icons are great during development, they require HTTP requests to fetch the icon and always use the latest version of the icon. It's possible the icon could change or be removed in the future. Additionally, the cache warming process will take significantly longer if using many _on-demand_ icons. You can think of importing the icon as locking it (similar to how composer.lock _locks_ your dependencies).

Icon Caching

To avoid having to parse icon files on every request, icons are cached. In production, you can pre-warm the cache by running the following command:

1

$ php bin/console ux:icons:warm-cache

This command looks in all your Twig templates for ux_icon() calls and <twig:ux:icon> tags and caches the icons it finds.

1
2
3
4
5
6
7
8
9

{# 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]) }}

TwigComponent

The ux_icon() function is optimized to be as fast as possible. To deliver the same level of performance when using the HTML syntax (<twig:ux:icon name="..." />), the TwigComponent overhead is reduced by calling the IconRenderer immediately and returning the HTML output.

1
2
3
4
5
6
7

{# The 🧸 will be ignored in the HTML output #}
<twig:ux:icon name="user-profile" class="w-4 h-4">🧸</twig:ux:icon>

{# Renders "user-profile.svg" #}
<svg viewBox="0 0 24 24" class="w-4 h-4">
    <path fill="currentColor" d="M21 7L9 19l-5.5-5.5l1.41-1.41L9 16.17L19.59 5.59z"/>
</svg>

Debugging Configuration

1
2
3
4
5

# 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

Full Configuration

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

# 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

       # Whether to use the "on demand" icons powered by Iconify.design
       on_demand: true

       # The endpoint for the Iconify API
       endpoint: 'https://api.iconify.design'

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