Twig Components

Naming Your Component

To give your component a name, TwigComponent looks at the namespace(s) configured in twig_component.yaml and finds the first match. If you have the recommended App\Twig\Components\, then:

The : character is used in the name instead of \. See Configuration for more info.

Instead of letting TwigComponent choose a name, you can also set one yourself:

1
2
3
4

#[AsTwigComponent('alert')]
class Alert
{
}

Passing Data (Props) into your Component

To make our Alert component reusable, we need the message and type (e.g. success, danger, etc) to be configurable. To do that, create a public property for each:

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

// src/Twig/Components/Alert.php
  // ...

  #[AsTwigComponent]
  class Alert
  {
+     public string $message;

+     public string $type = 'success';

      // ...
  }

In the template, the Alert instance is available via the this variable and public properties are available directly. Use them to render the two new properties:

1
2
3
4
5
6

<div class="alert alert-{{ type }}">
    {{ message }}

    {# Same as above, but using "this", which is the component object #}
    {{ this.message }}
</div>

How can we populate the message and type properties? By passing them as "props" via the a 2nd argument to component():

1
2
3
4
5
6

{{ component('Alert', {message: 'Successfully created!'}) }}

{{ component('Alert', {
    type: 'danger',
    message: 'Danger Will Robinson!'
}) }}

Behind the scenes, a new Alert will be instantiated and the message key (and type if passed) will be set onto the $message property of the object. Then, the component is rendered! If a property has a setter method (e.g. setMessage()), that will be called instead of setting the property directly.

1
2
3
4
5

#[AsTwigComponent(exposePublicProps: false)]
class Alert
{
    // ...
}

Passing & Rendering Attributes

If you pass extra props that are not settable on your component class, those can be rendered as attributes:

1
2
3
4

{{ component('Alert', {
    id: 'custom-alert-id',
    message: 'Danger Will Robinson!'
}) }}

To render the attributes, use the special attributes variable that's available in every component template:

1
2
3

<div {{ attributes.defaults({class: 'alert alert-' ~ type}) }}>
    {{ message }}
</div>

See Component Attributes to learn more.

Component Template Path

If you're using the default config, the template name will be: templates/components/{component_name}.html.twig, where {component_name} matches the component name.

Any : in the name are changed to subdirectories.

You can control the template used via the AsTwigComponent attribute:

1
2
3
4
5
6

// src/Twig/Components/Alert.php
  // ...

- #[AsTwigComponent]
+ #[AsTwigComponent(template: 'my/custom/template.html.twig')]
  class Alert

You can also configure the default template directory for an entire namespace. See Configuration.

Component HTML Syntax

So far so good! To make it really nice to work with Twig Components, it comes with an HTML-like syntax where props are passed as attributes:

1

<twig:Alert message="This is really cool!" withCloseButton />

This would pass a message and withCloseButton (true) props to the Alert component and render it! If an attribute is dynamic, prefix the attribute with : or use the normal {{ }} syntax:

1
2
3
4
5
6
7

<twig:Alert message="hello!" :user="user.id" />

// equal to
<twig:Alert message="hello!" user="{{ user.id }}" />

// pass object, array, or anything you imagine
<twig:Alert :foo="{col: ['foo', 'oof']}" />

Boolean props are converted using PHP's type juggling rules. The string "false" is converted to the boolean true.

To pass the boolean false, you can pass a Twig expression {{ false }} or use the dynamic syntax (with the : prefix):

1
2
3
4
5
6
7
8

{# ❌ the string 'false' is converted to the boolean 'true' #}
<twig:Alert message="..." withCloseButton="false" />

{# ✅ use the 'false' boolean value #}
<twig:Alert message="..." withCloseButton="{{ false }}" />

{# ✅ use the dynamic syntax #}
<twig:Alert message="..." :withCloseButton="false" />

Don't forget that you can mix and match props with attributes that you want to render on the root element:

1

<twig:Alert message="hello!" id="custom-alert-id" />

To pass an array of attributes, use {{...}} spread operator syntax. This requires Twig 3.7.0 or higher:

1

<twig:Alert {{ ...myAttributes }} />

We'll use the HTML syntax for the rest of the guide.

Passing HTML to Components

Instead of passing a message prop to the Alert component, what if we could do this?

1
2
3

<twig:Alert>
    I'm writing <strong>HTML</strong> right here!
</twig:Alert>

We can! When you add content between the <twig:Alert> open and close tag, it's passed to your component template as the block called content. You can render it like any normal block:

1
2
3

<div {{ attributes.defaults({class: 'alert alert-' ~ type}) }}>
    {% block content %}{% endblock %}
</div>

You can even give the block default content. See Passing HTML to Components via Block for more info.

Using macros in Components

Defining contents inside a component works great, but what if you want to use a macro inside a component? Good news: you can! But there's a catch: you cannot import macros using the _self keyword. Instead, you need to use the full path of the template where the macro is defined:

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

{% macro message_formatter(message) %}
    <strong>{{ message }}</strong>
{% endmacro %}

<twig:Alert>
    {# ❌ this won't work #}
    {% from _self import message_formatter %}

    {# ✅ this works as expected #}
    {% from 'path/of/this/template.html.twig' import message_formatter %}

    {{ message_formatter('...') }}
</twig:Alert>

The mount() Method

The mount() method gives you more control over how your "props" are handled. It is called once, immediately after the component is instantiated, but before the component system assigns the props you passed when rendering.

For example, if you call your component like this:

1

<twig:Alert type="error" message="..."/>

The following code won't work as expected:

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

// src/Twig/Components/Alert.php
// ...

#[AsTwigComponent]
class Alert
{
    public string $message;
    public string $type = 'success';

    public function mount(): void
    {
        {# ❌ this won't work: at this point $type still has its default value.
               Passed values are not yet available in props. #}
        if ('error' === $this->type) {
            // ...
        }
    }

    // ...
}

Inside mount(), each prop has only its default value (or null if it is untyped and has no default). If you need a prop's value, declare a parameter in mount() whose name matches the prop instead of reading the public property:

1
2
3
4
5
6
7
8

public function mount(string $type): void
{
    {# ✅ this works as expected: the $type argument in PHP has the value
           passed to the 'type' prop in the Twig template #}
    if ('error' === $type) {
        // ...
    }
}

If a prop name (e.g. type) matches an argument name in mount(), its value will be passed only to the method. The component system will not set it on a public property or use it in the component's attributes.

mount() can also receive props even when no matching public property exists. For example, pass an isError prop instead of type:

1

<twig:Alert isError="{{ true }}" message="..."/>

Define a $isError argument to capture the prop and initialize other properties using that value:

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

#[AsTwigComponent]
class Alert
{
    public string $message;
    public string $type = 'success';

    public function mount(bool $isError = false): void
    {
        if ($isError) {
            $this->type = 'danger';
        }
    }

    // ...
}

PreMount Hook

If you need to modify/validate data before it's mounted on the component use a PreMount hook:

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
28

// src/Twig/Components/Alert.php
use Symfony\Component\OptionsResolver\OptionsResolver;
use Symfony\UX\TwigComponent\Attribute\PreMount;
// ...

#[AsTwigComponent]
class Alert
{
    public string $message;
    public string $type = 'success';

    #[PreMount]
    public function preMount(array $data): array
    {
        // validate data
        $resolver = new OptionsResolver();
        $resolver->setIgnoreUndefined(true);

        $resolver->setDefaults(['type' => 'success']);
        $resolver->setAllowedValues('type', ['success', 'danger']);
        $resolver->setRequired('message');
        $resolver->setAllowedTypes('message', 'string');

        return $resolver->resolve($data) + $data;
    }

    // ...
}

1

$resolver->setIgnoreUndefined(true);

1

return $resolver->resolve($data) + $data;

The data returned from preMount() will be used as the props for mounting.

PostMount Hook

After a component is instantiated and its data mounted, you can run extra code via the PostMount hook:

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

// src/Twig/Components/Alert.php
use Symfony\UX\TwigComponent\Attribute\PostMount;
// ...

#[AsTwigComponent]
class Alert
{
    #[PostMount]
    public function postMount(): void
    {
        if (str_contains($this->message, 'danger')) {
            $this->type = 'danger';
        }
    }
    // ...
}

A PostMount method can also receive an array $data argument, which will contain any props passed to the component that have not yet been processed, (i.e. they don't correspond to any property and weren't an argument to the mount() method). You can handle these props, remove them from the $data and return the array:

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

// src/Twig/Components/Alert.php
#[AsTwigComponent]
class Alert
{
    public string $message;
    public string $type = 'success';

    #[PostMount]
    public function processAutoChooseType(array $data): array
    {
        if ($data['autoChooseType'] ?? false) {
            if (str_contains($this->message, 'danger')) {
                $this->type = 'danger';
            }

            // remove the autoChooseType prop from the data array
            unset($data['autoChooseType']);
        }

        // any remaining data will become attributes on the component
        return $data;
    }
    // ...
}

Context / Variables Inside of Blocks

The content inside of the <twig:Component> should be viewed as living in its own, independent template, which extends the component's template. This has a few interesting consequences.

First, inside of <twig:Component>, the this variable represents the component you're now rendering and you have access to all of that component's variables:

1
2
3
4
5
6
7
8

{# templates/components/SuccessAlert.html.twig #}
{{ this.someFunction }} {# this === SuccessAlert #}

<twig:Alert type="success">
    {{ this.someFunction }} {# this === Alert #}

    {{ type }} {# references a "type" prop from Alert #}
</twig:Alert>

Conveniently, in addition to the variables from the Alert component, you also have access to whatever variables are available in the original template:

1
2
3
4
5

{# templates/components/SuccessAlert.html.twig #}
{% set name = 'Fabien' %}
<twig:Alert type="success">
    Hello {{ name }}
</twig:Alert>

ALL variables from the upper component (e.g. SuccessAlert) are available inside the content of the lower component (e.g. Alert). However, because variables are merged, any variables with the same name are overridden by the lower component (e.g. Alert). That's why this refers to the embedded, or "current" component Alert.

There is also one special superpower when passing content to a component: your code executes as if it is "copy-and-pasted" into the block of the target template. This means you can access variables from the block you're overriding! For example:

1
2
3
4
5
6

{# templates/component/SuccessAlert.html.twig #}
{% for message in messages %}
    {% block alert_message %}
        A default {{ message }}
    {% endblock %}
{% endfor %}

When overriding the alert_message block, you have access to the message variable:

1
2
3
4
5
6

{# templates/some_page.html.twig #}
<twig:SuccessAlert>
    <twig:block name="alert_message">
        I can override the alert_message block and access the {{ message }} too!
    </twig:block>
</twig:SuccessAlert>

As mentioned before, variables from lower components are merged with those from upper components. When you need access to some properties or functions from higher components, that can be done via the outerScope... variable:

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

{# templates/SuccessAlert.html.twig #}
{% set name = 'Fabien' %}
{% set message = 'Hello' %}
{% component Alert with {type: 'success', name: 'Bart'} %}
    Hello {{ name }} {# Hello Bart #}

    {{ message }} {{ outerScope.name }} {# Hello Fabien #}

    {{ outerScope.this.someFunction }} {# this refers to SuccessAlert #}

    {{ outerScope.this.someProp }} {# references a "someProp" prop from SuccessAlert #}
{% endcomponent %}

You can keep referring to components higher up as well. Just add another outerScope. Remember though that the outerScope reference only starts once you're INSIDE the (embedded) component.

1
2
3
4
5
6
7
8
9
10
11

{# templates/FancyProfileCard.html.twig #}
{% component Card %}
    {% block header %}
        {% component Alert with {message: outerScope.this.someProp} %} {# not yet INSIDE the Alert template #}
            {% block content %}
                {{ message }} {# same value as below, indirectly refers to FancyProfileCard::someProp #}
                {{ outerScope.outerScope.this.someProp }} {# directly refers to FancyProfileCard::someProp #}
            {% endblock %}
        {% endcomponent %}
    {% endblock %}
{% endcomponent %}

Inheritance & Forwarding "Outer Blocks"

The content inside a <twig: component tag should be viewed as living in its own, independent template, which extends the component's template. This means that any blocks that live in the "outer" template are not available. However, you can access these via a special outerBlocks variable:

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

{% extends 'base.html.twig' %}

{% block call_to_action %}<strong>Attention! Free Puppies!</strong>{% endblock %}

{% block body %}
  <twig:Alert>
      {# this would NOT work... #}
      {{ block('call_to_action') }}

      {# ...but this works! #}
      {{ block(outerBlocks.call_to_action) }}
  </twig:Alert>
{% endblock %}

The outerBlocks variable becomes especially useful with nested components. For example, imagine we want to create a SuccessAlert component:

1
2
3
4

{# templates/some_page.html.twig #}
<twig:SuccessAlert>
    We will successfully <em>forward</em> this block content!
<twig:SuccessAlert>

We already have a generic Alert component, so let's re-use it:

1
2
3
4

{# templates/components/Alert.html.twig #}
<div {{ attributes.defaults({class: 'alert alert-'~type}) }}">
    {% block content %}{% endblock %}
</div>

To do this, the SuccessAlert component can grab the content block that's passed to it via the outerBlocks variable and forward it into Alert:

1
2
3
4

{# templates/components/SuccessAlert.html.twig #}
<twig:Alert type="success">
    {{ block(outerBlocks.content) }}
</twig:Alert>

By passing the original content block into the content block of Alert, this will work perfectly.

Defaults & Merging

In your component template, you can set defaults that are merged with passed attributes. The passed attributes override the default with the exception of class. For class, the defaults are prepended:

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

{# templates/components/MyComponent.html.twig #}
<button {{ attributes.defaults({class: 'bar', type: 'button'}) }}>Save</button>

{# render component #}
{{ component('MyComponent', {style: 'color:red'}) }}

{# renders as: #}
<button class="bar" type="button" style="color:red">Save</button>

{# render component #}
{{ component('MyComponent', {class: 'foo', type: 'submit'}) }}

{# renders as: #}
<button class="bar foo" type="submit">Save</button>

Render

You can take full control over the attributes that are rendered by using the render() method.

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

{# templates/components/MyComponent.html.twig #}
<div
  style="{{ attributes.render('style') }} display:block;"
  {{ attributes }} {# be sure to always render the remaining attributes! #}
>
  My Component!
</div>

{# render component #}
{{ component('MyComponent', {style: 'color:red;'}) }}

{# renders as: #}
<div style="color:red; display:block;">
  My Component!
</div>

Only

Extract specific attributes and discard the rest:

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

{# render component #}
{{ component('MyComponent', {class: 'foo', style: 'color:red'}) }}

{# templates/components/MyComponent.html.twig #}
<div {{ attributes.only('class') }}>
  My Component!
</div>

{# renders as: #}
<div class="foo">
  My Component!
</div>

Without

Exclude specific attributes:

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

{# render component #}
{{ component('MyComponent', {class: 'foo', style: 'color:red'}) }}

{# templates/components/MyComponent.html.twig #}
<div {{ attributes.without('class') }}>
  My Component!
</div>

{# renders as: #}
<div style="color:red">
  My Component!
</div>

Nested Attributes

You can have attributes that aren't meant to be used on the root element but one of its descendants. This is useful for, say, a dialog component where you want to allow customizing the attributes of the dialog's content, title, and footer. Here's an example of this:

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
28
29
30

{# templates/components/Dialog.html.twig #}
<div {{ attributes }}>
    <div {{ attributes.nested('title') }}>
        {% block title %}Default Title{% endblock %}
    </div>
    <div {{ attributes.nested('body') }}>
        {% block content %}{% endblock %}
    </div>
    <div {{ attributes.nested('footer') }}>
        {% block footer %}Default Footer{% endblock %}
    </div>
</div>

{# render #}
<twig:Dialog class="foo" title:class="bar" body:class="baz" footer:class="qux">
    Some content
</twig:MyDialog>

{# output #}
<div class="foo">
    <div class="bar">
        Default Title
    </div>
    <div class="baz">
        Some content
    </div>
    <div class="qux">
        Default Footer
    </div>
</div>

The nesting is recursive so you could potentially do something like this:

1
2
3
4
5
6
7

<twig:Form
    :form="form"
    class="ui-form"
    row:class="ui-form-row"
    row:label:class="ui-form-label"
    row:widget:class="ui-form-widget"
/>

CVA and Tailwind CSS

CVA integrates seamlessly with Tailwind CSS, though class conflicts may occur. Use the tailwind_merge() function from tales-from-a-dev/twig-tailwind-extra to resolve conflicts:

1
2
3

<div class="{{ alert.apply({color, size}, attributes.render('class'))|tailwind_merge }}">
    {% block content %}{% endblock %}
</div>

Compound Variants

Define compound variants for conditions involving multiple variants:

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
28
29
30
31

{# templates/components/Alert.html.twig #}
{% props color = 'blue', size = 'md' %}

{% set alert = cva({
    base: 'alert',
    variants: {
       color: { red: 'bg-red' },
       size: { lg: 'text-lg' }
    },
    compoundVariants: [{
        color: ['red'],
        size: ['lg'],
        class: 'font-bold'
    }]
}) %}

<div class="{{ alert.apply({color, size}) }}">
     {% block content %}{% endblock %}
</div>

{# index.html.twig #}

<twig:Alert color="red" size="lg">
    ...
</twig:Alert>

{# will render as: #}

<div class="alert bg-red text-lg font-bold">
    ...
</div>

Default Variants

If no variants match, you can define a default set of classes to apply:

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
28

{# templates/components/Alert.html.twig #}
{% set alert = cva({
    base: 'alert',
    variants: {
        color: {
            red: 'bg-red'
        },
        rounded: {
            sm: 'rounded-sm',
            md: 'rounded-md'
        }
    },
    defaultVariants: {
        rounded: 'md'
    }
}) %}

{# index.html.twig #}

<twig:Alert color="red">
    ...
</twig:Alert>

{# will render as: #}

<div class="alert bg-red rounded-md">
    ...
</div>

ExposeInTemplate Attribute

All public component properties are available directly in your component template. You can use the ExposeInTemplate attribute to expose private/protected properties and public methods directly in a component template (someProp vs this.someProp, someMethod vs this.someMethod). Properties must be accessible (have a getter). Methods cannot have required parameters:

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
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53

// ...
use Symfony\UX\TwigComponent\Attribute\ExposeInTemplate;

#[AsTwigComponent]
class Alert
{
    #[ExposeInTemplate]
    private string $message; // available as `{{ message }}` in the template

    #[ExposeInTemplate('alert_type')]
    private string $type = 'success'; // available as `{{ alert_type }}` in the template

    #[ExposeInTemplate(name: 'ico', getter: 'fetchIcon')]
    private string $icon = 'ico-warning'; // available as `{{ ico }}` in the template using `fetchIcon()` as the getter

    /**
     * Required to access $this->message
     */
    public function getMessage(): string
    {
        return $this->message;
    }

    /**
     * Required to access $this->type
     */
    public function getType(): string
    {
        return $this->type;
    }

    /**
     * Required to access $this->icon
     */
    public function fetchIcon(): string
    {
        return $this->icon;
    }

    #[ExposeInTemplate]
    public function getActions(): array // available as `{{ actions }}` in the template
    {
        // ...
    }

    #[ExposeInTemplate('dismissable')]
    public function canBeDismissed(): bool // available as `{{ dismissable }}` in the template
    {
        // ...
    }

    // ...
}

Computed Properties

In the previous example, instead of querying for the featured products immediately (e.g. in __construct()), we created a getProducts() method and called that from the template via this.products.

This was done because, as a general rule, you should make your components as lazy as possible and store only the information you need on its properties (this also helps if you convert your component to a live component later). With this setup, the query is only executed if and when the getProducts() method is actually called. This is very similar to the idea of "computed properties" in frameworks like Vue.

But there's no magic with the getProducts() method: if you call this.products multiple times in your template, the query would be executed multiple times.

To make your getProducts() method act like a true computed property, call computed.products in your template. computed is a proxy that wraps your component and caches the return of methods. If they are called additional times, the cached value is used.

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

{# templates/components/FeaturedProducts.html.twig #}
<div>
    <h3>Featured Products</h3>

    {% for product in computed.products %}
        ...
    {% endfor %}

    ...
    {% for product in computed.products %} {# use cache, does not result in a second query #}
        ...
    {% endfor %}
</div>

PreRenderEvent

Subscribing to the PreRenderEvent gives the ability to modify the twig template and twig variables before components are rendered:

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

use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Symfony\UX\TwigComponent\Event\PreRenderEvent;

class HookIntoTwigPreRenderSubscriber implements EventSubscriberInterface
{
    public function onPreRender(PreRenderEvent $event): void
    {
        $event->getComponent(); // the component object
        $event->getTemplate(); // the twig template name that will be rendered
        $event->getVariables(); // the variables that will be available in the template

        $event->setTemplate('some_other_template.html.twig'); // change the template used

        // manipulate the variables:
        $variables = $event->getVariables();
        $variables['custom'] = 'value';

        $event->setVariables($variables); // {{ custom }} will be available in your template
    }

    public static function getSubscribedEvents(): array
    {
        return [PreRenderEvent::class => 'onPreRender'];
    }
}

PostRenderEvent

The PostRenderEvent is called after a component has finished rendering and contains the MountedComponent that was just rendered.

PreCreateForRenderEvent

Subscribing to the PreCreateForRenderEvent gives the ability to be notified before a component object is created or hydrated, at the very start of the rendering process. You have access to the component name, input props and can interrupt the process by setting HTML. This event is not triggered during a re-render.

PreMountEvent and PostMountEvent

To run code just before or after a component's data is mounted, you can listen to PreMountEvent or PostMountEvent.

Anonymous Components

Using a component from a third-party bundle is just as straightforward as using one from your own application. Once the bundle is installed and configured, you can reference its components directly within your Twig templates:

1
2
3

<twig:Acme:Button type="primary">
    Click me
</twig:Acme:Button>

Here, the component name is composed of the bundle's Twig namespace Acme, followed by a colon, and then the component path Button.

The component must be located in the bundle's templates/components/ directory. For example, the component referenced as <twig:Acme:Button> should have its template file at templates/components/Button.html.twig within the Acme bundle.