ux-icons

UX Icons

Twig テンプレートでローカルおよびリモートの SVG アイコンをレンダリングします。アイコンはローカルファイル、Iconify.design（200 以上のアイコンセット、200,000 個以上のアイコン）、またはカスタムアイコンセットから取得できます。アイコンは <svg> 要素としてインライン化されるため、アイコンフォントも、実行時の外部リクエストもありません。

インストール

composer require symfony/ux-icons

クイックリファレンス

ux_icon('name')                        Twig function
ux_icon('name', {class: 'w-4 h-4'})   with HTML attributes
<twig:ux:icon name="name" />           Twig component (requires ux-twig-component)
<twig:ux:icon name="set:name" />       icon from a specific set

アイコンのレンダリング

Twig 関数

{{ ux_icon('menu') }}
{# renders <svg ...>...</svg> #}

{{ ux_icon('user-profile', {class: 'w-4 h-4'}) }}
{# renders <svg class="w-4 h-4"> ... </svg> #}

{{ ux_icon('user-profile', {height: '16px', width: '16px', 'aria-hidden': true}) }}
{# renders <svg height="16" width="16" aria-hidden="true"> ... </svg> #}

Twig コンポーネント（HTML 構文）

symfony/ux-twig-component が必要です。

<twig:ux:icon name="user-profile" class="w-4 h-4" />

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

<twig:ux:icon name="user-profile" height="16" width="16" aria-hidden="true" />

コンポーネントに追加する、または関数に渡す HTML 属性は、すべて <svg> 要素にレンダリングされます。

アイコン名

ローカルアイコン

デフォルトでは assets/icons/ に保存されます。ファイルパスから .svg を除いたものがアイコン名になります。

assets/icons/
  ├─ close.svg           → ux_icon('close')
  ├─ menu.svg            → ux_icon('menu')
  └─ header/
     └─ logo.svg         → ux_icon('header:logo')

サブディレクトリは : 区切りのプレフィックスになります。アプリのロゴやカスタムイラストなど、プロジェクト固有の SVG にはローカルアイコンを使用してください。

Iconify（オンデマンド）

prefix:name 構文を使うと、任意の Iconify セットからアイコンを取得できます。

{# UI icons #}
{{ ux_icon('lucide:arrow-right') }}     {# Lucide #}
{{ ux_icon('tabler:heart') }}           {# Tabler #}
{{ ux_icon('heroicons:star-solid') }}   {# Heroicons #}
{{ ux_icon('mdi:check') }}              {# Material Design Icons #}

{# Country flags #}
<twig:ux:icon name="flagpack:fr" />
<twig:ux:icon name="flagpack:{{ country.code|lower }}" />

{# Brand logos #}
<twig:ux:icon name="simple-icons:symfony" />
<twig:ux:icon name="simple-icons:github" />

{# File type icons #}
<twig:ux:icon name="bi:filetype-pdf" />
<twig:ux:icon name="bi:filetype-{{ file.extension }}" />

オンデマンドアイコンは Iconify API から取得され、ローカルにキャッシュされた後、SVG としてインライン化されます。本番環境では実行時の HTTP リクエストは発生しません。

利用可能なすべてのセットは https://icon-sets.iconify.design/ で確認できます。

設定

# config/packages/ux_icons.yaml
ux_icons:
    # Local directory for icon SVG files
    icon_dir: '%kernel.project_dir%/assets/icons'

    # Default HTML attributes added to every icon
    default_icon_attributes:
        fill: currentColor
        'font-size': '1.25em'

    # Aliases: shortcut name => full icon name
    aliases:
        dots: 'clarity:ellipsis-horizontal-line'
        'tabler:save': 'tabler:device-floppy'

    # Iconify integration
    iconify:
        enabled: true
        on_demand: true
        endpoint: 'https://api.iconify.design'

    # Silently ignore missing icons (renders nothing instead of throwing)
    ignore_not_found: false

アイコンセット

独自のプレフィックス、ソース、デフォルト属性を持つカスタムアイコンセットを定義します。

ux_icons:
    icon_sets:
        # Local directory with custom attributes
        flags:
            path: '%kernel.project_dir%/assets/images/flags'
            icon_attributes:
                class: 'flag'
                fill: false           # "false" removes a default attribute

        # Alias an entire Iconify set under a shorter prefix
        icons:
            alias: 'lucide'           # ux_icon('icons:arrow-right') → lucide:arrow-right

エイリアス

よく使うアイコンのショートカットを作成します。

ux_icons:
    aliases:
        dots: 'clarity:ellipsis-horizontal-line'
        save: 'lucide:save'
        delete: 'lucide:trash-2'
        'tabler:save': 'tabler:device-floppy'   # can also remap within a set

{{ ux_icon('dots') }}    {# resolves to clarity:ellipsis-horizontal-line #}
{{ ux_icon('save') }}    {# resolves to lucide:save #}

CLI コマンド

アイコンをローカルにインポート

Iconify からローカルの assets/icons/ ディレクトリにアイコンをダウンロードします。

# Import a single icon
php bin/console ux:icons:import flowbite:user-solid

# Import multiple icons
php bin/console ux:icons:import flowbite:user-solid flowbite:home-solid

# Force overwrite existing files
php bin/console ux:icons:import flowbite:user-solid --force

すべてのオンデマンドアイコンをロック

オンデマンドで現在使用されているすべてのアイコンをローカルファイルにダウンロードします（依存関係のロックに似ています）。

php bin/console ux:icons:lock

# Force overwrite
php bin/console ux:icons:lock --force

# Verbose output (helps spot invalid icon names)
php bin/console ux:icons:lock -v

アクセシビリティ

アイコンはデフォルトで装飾目的として扱われます。意味のあるアイコンには aria-label を追加してください。

{# Decorative (hidden from screen readers) #}
{{ ux_icon('lucide:star', {'aria-hidden': true}) }}

{# Meaningful (announced by screen readers) #}
{{ ux_icon('lucide:star', {'aria-label': 'Favorite', role: 'img'}) }}

主な原則

アイコンは SVG としてインライン化されます。 アイコンフォントも、<img> タグも、実行時の外部 HTTP リクエストもありません。SVG マークアップは HTML に直接埋め込まれます。そのため、アイコンは currentColor を継承し、CSS でスタイルを設定でき、オフラインでも動作します。

オンデマンドは開発用です。 開発中は、必要に応じてオンデマンドモードが Iconify からアイコンを取得します。本番環境では、ux:icons:lock を実行して、使用するすべてのアイコンをローカルにダウンロードしてください。

属性はカスケードします。 設定のデフォルト属性 < アイコンセットの属性 < アイコンごとの属性、の順で適用されます。特定のセットまたはアイコンのデフォルト属性を削除するには、false を使用してください。

HTML 構文を優先してください。 <twig:ux:icon name="..." /> はテンプレートで読みやすく、ほかの UX コンポーネントとも一貫性があります。

リファレンス

• API と設定（すべてのオプション、属性、アイコンセット）：references/api.md
• パターン（一般的なレシピ、スタイリング、動的アイコン）：references/patterns.md
• 注意点（よくある間違い、デバッグ、キャッシュ）：references/gotchas.md