Skip to content

smnandre/symfony-ux-skills / skills/twig-component

twig-component

Verified

Symfony UX TwigComponent for reusable UI building blocks -- server-rendered components with PHP classes and Twig templates. Use when creating buttons, cards, alerts, badges, navbars, or any reusable UI element with props, blocks/slots, computed properties, or anonymous (template-only) components. Code triggers: AsTwigComponent, #[AsTwigComponent], ExposeInTemplate, PreMount, PostMount, <twig:Alert />, <twig:Button>, component(), computed properties, anonymous component, HTML syntax. Also trigger when the user asks "how to create a reusable component", "how to make a component library", "how to pass props to a component", "how to use slots/blocks in a component", "how to build a design system in Symfony", "what is the HTML syntax for components", "how to create a component without a PHP class". Do NOT trigger for components that re-render dynamically on user input (use live-component), for JS behavior (use stimulus), or for page navigation (use turbo).

FileKindSize
SKILL.mdskill md9.6 KB
references/api.mdmarkdown7.7 KB
references/gotchas.mdmarkdown7.3 KB
references/patterns.mdmarkdown11.8 KB

references/gotchas.md

View on GitHub
# TwigComponent Gotchas & Debugging

## Attributes

### Missing `{{ attributes }}` on Root Element

```twig
{# WRONG: no attributes on root -- extra HTML attributes are silently lost #}
<div class="alert alert-{{ type }}">
    {{ message }}
</div>

{# CORRECT: attributes rendered on root element #}
<div class="alert alert-{{ type }}" {{ attributes }}>
    {{ message }}
</div>
```

Without `{{ attributes }}`, any HTML attributes passed when using the component (e.g., `<twig:Alert class="mb-4" id="main-alert" />`) are silently dropped.

### Attributes Merge with Existing

```twig
{# Component template #}
<div class="alert" {{ attributes }}>

{# Usage #}
<twig:Alert class="mb-4" />

{# Renders as: <div class="alert mb-4"> -- classes are MERGED #}
```

`{{ attributes }}` merges `class` values. Other attributes (like `id`, `style`, `data-*`) are added or overwritten. If you don't want merging, use `{{ attributes.without('class') }}`.

### Rendering Attributes on the Wrong Element

```twig
{# WRONG: attributes on inner element, root has no attributes #}
<div>
    <button {{ attributes }}>Click me</button>
</div>

{# CORRECT: attributes on root element #}
<div {{ attributes }}>
    <button>Click me</button>
</div>
```

Attributes should always go on the **root** element of the component template.

---

## Naming and Resolution

### Component Name Doesn't Match Class

```php
// This component is available as "Alert" (class name, not file name)
#[AsTwigComponent]
final class Alert { }

// Template must be: templates/components/Alert.html.twig

// If you customize the name:
#[AsTwigComponent(name: 'ui:alert')]
final class Alert { }
// Template: templates/components/ui/alert.html.twig
// Usage: <twig:ui:alert />
```

### Template Not Found

```
# Expected path for component "Alert":
templates/components/Alert.html.twig    # default
templates/components/alert.html.twig    # WRONG (case-sensitive!)

# Expected path for component "ui:alert":
templates/components/ui/alert.html.twig
```

The template path is derived from the component name. Colons (`:`) become directory separators.

### Anonymous Component Not Discovered

Anonymous components (no PHP class) must be in the `anonymous_template_directory`:

```yaml
# config/packages/twig_component.yaml
twig_component:
    anonymous_template_directory: 'components/'
    defaults:
        App\Twig\Components\: 'components/'
```

```
# Template location:
templates/components/Badge.html.twig    # <twig:Badge />
templates/components/ui/Tag.html.twig   # <twig:ui:Tag />
```

If the template exists but the component isn't found, check the directory config.

---

## Props

### Undeclared Props Become Attributes

```php
#[AsTwigComponent]
final class Button
{
    public string $label;
}
```

```twig
{# "variant" is not a prop -- it becomes an HTML attribute #}
<twig:Button label="Save" variant="primary" />

{# Renders: <button variant="primary">Save</button> -- probably not what you want #}
```

If a value passed to a component doesn't match a declared property, it silently goes into `{{ attributes }}`. This can be confusing. Declare all expected props.

### Required Props Not Provided

```twig
{# This will throw an error if "label" has no default #}
<twig:Button />

{# Fix: either provide the prop or add a default in PHP #}
<twig:Button label="Save" />
```

### Prop Type Mismatch

```twig
{# WRONG: passing string "true" instead of boolean true #}
<twig:Toggle enabled="true" />

{# CORRECT: use : prefix for expressions #}
<twig:Toggle :enabled="true" />
<twig:Toggle :count="42" />
<twig:Toggle :items="['a', 'b']" />
```

The `:` prefix evaluates the value as a Twig expression. Without it, the value is always a string.

---

## Blocks and Slots

### Block Name Collision with Parent Layout

```twig
{# Component template #}
<div {{ attributes }}>
    {% block content %}{% endblock %}
</div>
```

If your component's block name conflicts with a block in the parent layout, unexpected things happen. Use specific names:

```twig
{# BETTER: use prefixed or specific block names #}
<div {{ attributes }}>
    {% block card_content %}{% endblock %}
</div>
```

### Nested Component Block Scope

```twig
{# Blocks only apply to the IMMEDIATE component, not nested ones #}
<twig:Card>
    <twig:block name="header">Card Header</twig:block>

    <twig:Button>
        {# This block is for Button, NOT for Card #}
        <twig:block name="content">Button Content</twig:block>
    </twig:Button>
</twig:Card>
```

### outerScope for Accessing Parent Variables

Inside a component template, the parent's Twig variables are NOT available. Use `outerScope`:

```twig
{# Parent template #}
{% set color = 'blue' %}
<twig:Badge />

{# Badge.html.twig -- this.color is NOT "blue" #}
{# Use outerScope to access parent variables: #}
<span class="badge badge-{{ outerScope.color }}">{{ label }}</span>
```

---

## PreMount and Mount

### PreMount Validation Runs Before Mount

```php
#[AsTwigComponent]
final class Pagination
{
    public int $page;
    public int $total;

    #[PreMount]
    public function preMount(array $data): array
    {
        // This runs BEFORE mount() and receives the raw data
        // Use it for validation or transformation
        if (isset($data['page']) && $data['page'] < 1) {
            $data['page'] = 1;
        }
        return $data;
    }
}
```

### Mount Is Called After Property Assignment

```php
#[AsTwigComponent]
final class DataTable
{
    public array $items = [];
    public int $perPage = 10;

    private array $paginatedItems;

    public function mount(): void
    {
        // Properties are already set when mount() is called
        $this->paginatedItems = array_slice($this->items, 0, $this->perPage);
    }
}
```

---

## Computed Properties

### Computed Methods Are Cached Per Render

```php
#[AsTwigComponent]
final class ExpensiveComponent
{
    #[ExposeInTemplate]
    public function expensiveCalculation(): array
    {
        // This is called ONCE per render, even if used multiple times in template
        return $this->repository->findAll();
    }
}
```

```twig
{# Both access the same cached result #}
{{ this.expensiveCalculation|length }} items
{% for item in this.expensiveCalculation %}
    ...
{% endfor %}
```

---

## HTML vs Twig Syntax

### Self-Closing vs Block Syntax

```twig
{# Self-closing: no blocks needed #}
<twig:Alert type="success" message="Done!" />

{# Block syntax: when you need to pass blocks #}
<twig:Card>
    <twig:block name="header">Title</twig:block>
    Content here
</twig:Card>

{# WRONG: self-closing with blocks (blocks are ignored) #}
<twig:Card header="Title" />
{# This only works if "header" is a prop, not a block #}
```

### Expression Syntax

```twig
{# Static string value #}
<twig:Alert type="success" />

{# Dynamic Twig expression (note the : prefix) #}
<twig:Alert :type="alertType" />
<twig:Alert :type="isError ? 'danger' : 'info'" />
<twig:UserCard :user="app.user" />
```

---

## Debugging

### Check Component Registration

```bash
php bin/console debug:twig-component
```

Lists all registered components, their class, template path, and type (live or not).

### Component Not Rendering

1. Check the component name matches exactly (case-sensitive)
2. Check the template exists at the expected path
3. Check the class has `#[AsTwigComponent]`
4. Check the `defaults` config maps the namespace correctly
5. Clear the cache: `php bin/console cache:clear`
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: 322kUpdated 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