Customize the Twig Template

You can customize the template used to render the component by passing it as the second argument to the AsTwigComponent attribute:

1
2
3
4
5
6
7
8
9

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

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

Twig Template Namespaces

You can use a : in your component's name to indicate a namespace. The default template will replace the : with /. For example, a component with the name form:input will look for a template in templates/components/form/input.html.twig.

The mount() Method

If, for some reason, you don't want an option to the component() function to be set directly onto a property, you can, instead, create a mount() method in your component:

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';
    }

    // ...
}

The mount() method is called just one time immediately after your component is instantiated. Because the method has an $isSuccess argument, we can pass an isSuccess option when rendering the component:

1
2
3
4

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

If an option name matches an argument name in mount(), the option is passed as that argument and the component system will not try to set it directly on a property.

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

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

    // ...
}

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

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. because they don't correspond to any property. 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/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;
    }
    // ...
}

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>

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>

Only

Extract specific attributes and discard the rest:

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>

Without

Exclude specific attributes:

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>

Inheritance & Forwarding "Outer Blocks"

The content inside a {% 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 inside the {% component %} tag. However, a special outerBlocks variable is added as a way to refer to those blocks:

1
2
3
4
5
6
7
8
9

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

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

{% block body %}
  {% component Alert %}
    {% block content %}{{ block(outerBlocks.call_to_action) }}{% endblock %}
  {% endcomponent %}
{% endblock %}

The outerBlocks variable becomes specially useful with nested components. For example, imagine we want to create a SuccessAlert component that's usable like this:

1
2
3
4

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

But we already have a generic Alert component, and we want to re-use it:

1
2
3
4

{# templates/Alert.html.twig #}
<div 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/SuccessAlert.html.twig #}
{% component Alert with { type: 'success' } %}
    {% block content %}{{ block(outerBlocks.content) }}{% endblock %}
{% endcomponent %}

Note that to pass a block multiple components down, each component needs to pass it.

Context / Variables Inside of Blocks

The content inside of the {% component ... %} should be viewed as living in its own, independent template, which extends the component's template. This has a few interesting consequences.

First, once you're inside of {% 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/SuccessAlert.html.twig #}
{{ this.someFunction }} {# this refers to SuccessAlert #}

{% component Alert with { type: 'success' } %}
    {{ this.someFunction }} {# this refers to Alert! #}

    {{ type }} {# references a "type" prop from Alert #}
{% endcomponent %}

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

1
2
3
4
5

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

Note that ALL variables from upper components (e.g. SuccessAlert) are available to lower components (e.g. Alert). However, because variables are merged, variables with the same name are overridden by lower components (that's also why this refers to the embedded, or "current" component).

The most interesting thing is that the content inside of {% component ... %} is executed 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/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 #}
{% component SuccessAlert %}
    {% block alert_message %}
        I can override the alert_message block and access the {{ message }} too!
    {% endblock %}
{% endcomponent %}

Passing Props as HTML Attributes

Passing props is done with HTML attributes. For example if you have this component:

1
2
3
4
5
6
7

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

You can pass the message, withActions or type props as attributes:

1
2

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

To pass in a dynamic value, 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 }}" />

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

To forward attributes to another component, use `{{...}}` spread operator syntax. This requires Twig 3.7.0 or higher:

1

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

Passing Content (Blocks) to Components

You can also pass content directly to your component:

1
2
3

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

In your component template, this becomes a block named content:

1
2
3
4
5

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

In addition to the default block, you can also add named blocks:

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>

And in your component template you can access your embedded block

1
2
3
4

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