Installation

Let's get this thing installed! Run:

1

$ composer require symfony/ux-twig-component

That's it! We're ready to go!

Creating a Basic Component

Let's create a reusable "alert" element that we can use to show success or error messages across our site. Step 1 is always to create a component that has an AsTwigComponent class attribute. Let's start as simple as possible:

1
2
3
4
5
6
7
8
9

// src/Components/Alert.php
namespace App\Components;

use Symfony\UX\TwigComponent\Attribute\AsTwigComponent;

#[AsTwigComponent]
class Alert
{
}

Step 2 is to create a template for this component. By default, templates live in templates/components/{component_name}.html.twig, where {component_name} matches the class name of the component:

1
2
3
4

{# templates/components/Alert.html.twig #}
<div class="alert alert-success">
    Success! You've created a Twig component!
</div>

This isn't very interesting yet… since the message is hardcoded into the template. But it's enough! Celebrate by rendering your component from any other Twig template:

1

{{ component('Alert') }}

Done! You've just rendered your first Twig Component! Take a moment to fist pump - then come back!

Naming Your Component

The name of your component is the class name by default. But you can customize it by passing an argument to AsTwigComponent:

1
2
3
4

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

Passing Data into your Component

Good start: but this isn't very interesting yet! To make our Alert component reusable, we need to make the message and type (e.g. success, danger, etc) configurable. To do that, create a public property for each:

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

// src/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 a 2nd argument to the component() function when rendering:

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
{
    // ...
}

1
2
3
4
5
6
7
8
9

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

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

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

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

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

    public function mount(bool $isSuccess = true)
    {
        $this->type = $isSuccess ? 'success' : 'danger';
    }

    // ...
}

1
2
3
4

{{ component('alert', {
    isSuccess: false,
    message: 'Danger Will Robinson!'
}) }}

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

// src/Components/Alert.php
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->setDefaults(['type' => 'success']);
        $resolver->setAllowedValues('type', ['success', 'danger']);
        $resolver->setRequired('message');
        $resolver->setAllowedTypes('message', 'string');

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

    // ...
}

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

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

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

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/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;
    }
    // ...
}

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
    {
        // ...
    }

    // ...
}

Fetching Services

Let's create a more complex example: a "featured products" component. You could choose to pass an array of Product objects into the component() function and set those on a $products property. But instead, let's allow the component to do the work of executing the query.

How? Components are services, which means autowiring works like normal. This example assumes you have a Product Doctrine entity and ProductRepository:

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

// src/Components/FeaturedProducts.php
namespace App\Components;

use App\Repository\ProductRepository;
use Symfony\UX\TwigComponent\Attribute\AsTwigComponent;

#[AsTwigComponent]
class FeaturedProducts
{
    private ProductRepository $productRepository;

    public function __construct(ProductRepository $productRepository)
    {
        $this->productRepository = $productRepository;
    }

    public function getProducts(): array
    {
        // an example method that returns an array of Products
        return $this->productRepository->findFeatured();
    }
}

In the template, the getProducts() method can be accessed via this.products:

1
2
3
4
5
6
7
8

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

    {% for product in this.products %}
        ...
    {% endfor %}
</div>

And because this component doesn't have any public properties that we need to populate, you can render it with:

1

{{ component('FeaturedProducts') }}

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>

Component Attributes

A common need for components is to configure/render attributes for the root node. Attributes are any data passed to component() that cannot be mounted on the component itself. This extra data is added to a ComponentAttributes that is available as attributes in your component's template.

To use, in your component's template, render the attributes variable in the root element:

1
2
3
4

{# templates/components/MyComponent.html.twig #}
<div{{ attributes }}>
  My Component!
</div>

When rendering the component, you can pass an array of html attributes to add:

1
2
3
4
5
6

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

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

Set an attribute's value to true to render just the attribute name:

1
2
3
4
5
6
7
8

{# templates/components/MyComponent.html.twig #}
<input{{ attributes}}/>

{# render component #}
{{ component('MyComponent', { type: 'text', value: '', autofocus: true }) }}

{# renders as: #}
<input type="text" value="" autofocus/>

Set an attribute's value to false to exclude the attribute:

1
2
3
4
5
6
7
8

{# templates/components/MyComponent.html.twig #}
<input{{ attributes}}/>

{# render component #}
{{ component('MyComponent', { type: 'text', value: '', autofocus: false }) }}

{# renders as: #}
<input type="text" value=""/>

To add a custom Stimulus controller to your root component element:

1

<div {{ attributes.defaults(stimulus_controller('my-controller', { someValue: 'foo' })) }}>

1
2
3
4
5

#[AsTwigComponent(attributesVar: '_attributes')]
class Alert
{
    // ...
}

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>

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

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

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

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

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

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

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

{# renders as: #}
<div style="color:red">
  My Component!
</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.

Nested Components

It's totally possible to nest one component into another. When you do this, there's nothing special to know: both components render independently. If you're using Live Components, then there are some guidelines related to how the re-rendering of parent and child components works. Read Live Nested Components.

Embedded Components

You can write your component's Twig template with blocks that can be overridden when rendering using the {% component %} syntax. These blocks can be thought of as slots which you may be familiar with from Vue. The component tag is very similar to Twig's native embed tag.

Consider a data table component. You pass it headers and rows but can expose blocks for the cells and an optional footer:

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

{# templates/components/DataTable.html.twig #}
<div{{ attributes.defaults({class: 'data-table'}) }}>
    <table>
        <thead>
            <tr>
                {% for header in this.headers %}
                    <th class="{% block th_class %}data-table-header{% endblock %}">
                        {{ header }}
                    </th>
                {% endfor %}
            </tr>
        </thead>
        <tbody>
            {% for row in this.data %}
                <tr>
                    {% for cell in row %}
                        <td class="{% block td_class %}data-table-cell{% endblock %}">
                            {{ cell }}
                        </td>
                    {% endfor %}
                </tr>
            {% endfor %}
        </tbody>
    </table>
    {% block footer %}{% endblock %}
</div>

When rendering, you can override the th_class, td_class, and footer blocks. The with data is what's mounted on the component object.

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

{# templates/some_page.html.twig #}
{% component DataTable with {headers: ['key', 'value'], data: [[1, 2], [3, 4]]} %}
    {% block th_class %}{{ parent() }} text-bold{% endblock %}

    {% block td_class %}{{ parent() }} text-italic{% endblock %}

    {% block footer %}
        <div class="data-table-footer">
            My footer
        </div>
    {% endblock %}
{% endcomponent %}

Component HTML Syntax

Twig Components come with an HTML-like syntax to ease the readability of your template:

1
2
3

<twig:Alert></twig:Alert>
// or use a self-closing tag
<twig:Alert />

1
2
3
4
5
6
7

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

1
2

// withActions will be set to true
<twig:Alert type="info" message="hello!" withActions />

1
2
3
4
5
6
7

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

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

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

1
2
3

<twig:Alert type="success">
    <div>Congratulations! You've won a free puppy!</div>
</twig:Alert>

1
2
3
4
5

<div class="alert alert-{{ type }}">
    {% block content %}
        // the content will appear in here
    {% endblock %}
 </div>

1
2
3
4
5
6
7

<twig:Alert type="success">
    <div>Congrats on winning a free puppy!</div>

    <twig:block name="footer">
        <button class="btn btn-primary">Claim your prize</button>
    </twig:block>
</twig:Alert>

1
2
3
4

<div class="alert alert-{{ type }}">
    {% block content %}{% endblock %}
    {% block footer %}{% endblock %}
 </div>

Contributing

Interested in contributing? Visit the main source for this repository: https://github.com/symfony/ux/tree/main/src/TwigComponent.

Backward Compatibility promise

This bundle aims at following the same Backward Compatibility promise as the Symfony framework: https://symfony.com/doc/current/contributing/code/bc.html