Skip to content

smnandre/symfony-ux-skills / skills/ux-icons

ux-icons

Verified

Symfony UX Icons for rendering SVG icons in Twig templates. Supports 200,000+ Iconify icons (Lucide, Heroicons, Tabler, Material Design, etc.), local SVG files, and custom icon sets with aliases. Use when displaying icons, configuring icon defaults, importing or locking on-demand icons, creating icon aliases, or styling SVG icons with CSS. Code triggers: <twig:ux:icon />, ux_icon(), UX_ICONS_DEFAULT_ICON_ATTRIBUTES, icon.yaml, icons/, iconify:, lucide:, heroicons:, tabler:, mdi:, bin/console ux:icons:lock, bin/console ux:icons:import. Also trigger when the user asks "how to add an icon", "how to use Lucide/Heroicons/Tabler icons", "how to render an SVG icon in Twig", "how to lock icons for production", "how to create icon aliases", "how to style an icon", "icon not found", "icon not rendering". Do NOT trigger for interactive maps (use ux-map) or general Twig components (use twig-component).

FileKindSize
SKILL.mdskill md7.3 KB
references/api.mdmarkdown4.5 KB
references/gotchas.mdmarkdown3.7 KB
references/patterns.mdmarkdown3.9 KB

references/gotchas.md

View on GitHub
# UX Icons Gotchas & Debugging

## Icon Not Found

### Wrong Name Format

```twig
{{ ux_icon('lucide/arrow-right') }}    {# WRONG: slash #}
{{ ux_icon('lucide:arrow-right') }}    {# CORRECT: colon separator #}

{{ ux_icon('lucide:ArrowRight') }}     {# WRONG: camelCase #}
{{ ux_icon('lucide:arrow-right') }}    {# CORRECT: kebab-case #}
```

### Local Icon Path Mismatch

```
assets/icons/header/logo.svg     → ux_icon('header:logo')      CORRECT
assets/icons/header/logo.svg     → ux_icon('header/logo')      WRONG
assets/icons/Header/Logo.svg     → ux_icon('header:logo')      WRONG (case-sensitive)
```

### Missing Iconify Prefix

```twig
{{ ux_icon('arrow-right') }}           {# looks in local icons only #}
{{ ux_icon('lucide:arrow-right') }}    {# fetches from Iconify #}
```

---

## On-Demand Not Working

### Iconify Disabled

```yaml
ux_icons:
    iconify:
        enabled: true      # must be true
        on_demand: true     # must be true for development
```

### Network Issues

On-demand requires HTTP access to `api.iconify.design`. If your dev environment has no internet (Docker without network, VPN restrictions), import icons locally:

```bash
php bin/console ux:icons:import lucide:arrow-right
```

### Cache Issues

Clear the cache after config changes:

```bash
php bin/console cache:clear
```

---

## Default Attributes Conflicts

### fill vs stroke Icons

Lucide and Tabler use `stroke`, not `fill`. Setting `fill: currentColor` globally can break them:

```yaml
# PROBLEM: breaks stroke-based icon sets
ux_icons:
    default_icon_attributes:
        fill: currentColor

# BETTER: use per-set attributes
ux_icons:
    default_icon_attributes: {}
    icon_sets:
        mdi:
            alias: 'mdi'
            icon_attributes:
                fill: currentColor
        lucide:
            alias: 'lucide'
            icon_attributes:
                stroke: currentColor
                fill: none
```

Or keep it simple -- most icons work with just `currentColor` on the parent:

```css
.icon {
    color: currentColor;
    width: 1.25em;
    height: 1.25em;
}
```

---

## Attribute Removal

To remove a default attribute for a specific icon set, set it to `false` in the set's `icon_attributes`. Using `false` removes the attribute entirely; using `''` (empty string) keeps it with an empty value.

See [api.md > Attribute Merge Order](api.md#attribute-merge-order) for the full priority chain and a YAML example.

---

## Production Deployment

### Always Lock Icons Before Deploying

On-demand mode makes HTTP requests. In production, all icons should be local:

```bash
# Before deployment
php bin/console ux:icons:lock

# Or set on_demand to false in production
# config/packages/prod/ux_icons.yaml
ux_icons:
    iconify:
        on_demand: false
```

### ignore_not_found in Production

```yaml
# config/packages/prod/ux_icons.yaml
ux_icons:
    ignore_not_found: true    # renders nothing instead of 500 error
```

---

## SVG File Requirements

Local SVG files must be valid SVG:

```xml
<!-- GOOD -->
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
    <path d="M12 2L2 22h20L12 2z"/>
</svg>

<!-- BAD: missing xmlns -->
<svg viewBox="0 0 24 24">
    <path d="M12 2L2 22h20L12 2z"/>
</svg>

<!-- BAD: includes width/height that override sizing -->
<svg width="512" height="512" viewBox="0 0 24 24">
    ...
</svg>
```

Best practice: SVG files should have `xmlns` and `viewBox` but no hardcoded `width`/`height`.

---

## TwigComponent Required for HTML Syntax

```twig
{# This requires symfony/ux-twig-component #}
<twig:ux:icon name="lucide:check" />

{# This works without it #}
{{ ux_icon('lucide:check') }}
```

If you get an error about `twig:ux:icon` not being recognized, install the TwigComponent package:

```bash
composer require symfony/ux-twig-component
```
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 323kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall