Debouncing

If the user types 5 characters really quickly, we don't want to send 5 Ajax requests. Fortunately, live components adds automatic debouncing: it waits for a 150ms pause between typing before sending an Ajax request to re-render. This is built in, so you don't need to think about it. But, you can delay via the debounce modifier:

1

<input data-model="debounce(100)|max">

Lazy Updating on "change" of a Field

Sometimes, you might want a field to re-render only after the user has changed an input and moved to another field. Browsers dispatch a change event in this situation. To re-render when this event happens, use the on(change) modifier:

1

<input data-model="on(change)|max">

Deferring a Re-Render Until Later

Other times, you might want to update the internal value of a property, but wait until later to re-render the component (e.g. until a button is clicked). To do that, use norender modifier:

1

<input data-model="norender|max">

Now, as you type, the max "model" will be updated in JavaScript, but it won't, yet, make an Ajax call to re-render the component. Whenever the next re-render does happen, the updated max value will be used.

Using name="" instead of data-model

If you're building a form (more on forms later), instead of adding data-model to every field, you can instead rely on the name attribute.

To activate this, you must add a data-model attribute to the <form> element:

1
2
3
4
5
6
7
8
9
10

<div {{ attributes }}>
    <form data-model="*">
        <input
            name="max"
            value="{{ max }}"
        >

        // ...
    </form>
</div>

The * value of data-model is not necessary, but is commonly used. You can also use the normal modifiers, like data-model="on(change)|*" to, for example, only send model updates for the change event of each field inside.

JavaScript Component Hooks

The JavaScript Component object has a number of hooks that you can use to run code during the lifecycle of your component. To hook into the component system from Stimulus:

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

// assets/controllers/some-custom-controller.js
// ...
import { getComponent } from '@symfony/ux-live-component';

export default class extends Controller {
    async initialize() {
        this.component = await getComponent(this.element);

        this.component.on('render:finished', (component) => {
            // do something after the component re-renders
        });
    }
}

The following hooks are available (along with the arguments that are passed):

• connect args (component: Component)
• disconnect args (component: Component)
• render:started args (html: string, response: BackendResponse, controls: { shouldRender: boolean })
• render:finished args (component: Component)
• response:error args (backendResponse: BackendResponse, controls: { displayError: boolean })
• loading.state:started args (element: HTMLElement, request: BackendRequest)
• loading.state:finished args (element: HTMLElement)
• model:set args (model: string, value: any, component: Component)

Adding a Stimulus Controller to your Component Root Element

The add() method was introduced in TwigComponents 2.7.

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

1

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

Adding and Removing Classes or Attributes

Instead of hiding or showing an entire element, you could add or remove a class:

1
2
3
4
5
6
7
8

<!-- add this class when loading -->
<div data-loading="addClass(opacity-50)">...</div>

<!-- remove this class when loading -->
<div data-loading="removeClass(opacity-50)">...</div>

<!-- add multiple classes when loading -->
<div data-loading="addClass(opacity-50 disabled)">...</div>

Sometimes you may want to add or remove an attribute when loading. That can be accomplished with addAttribute or removeAttribute:

1
2

<!-- add the "disabled" attribute when loading -->
<div data-loading="addAttribute(disabled)">...</div>

You can also combine any number of directives by separating them with a space:

1

<div data-loading="addClass(opacity-50) addAttribute(disabled)">...</div>

Finally, you can add the delay modifier to not trigger the loading changes until loading has taken longer than a certain amount of time:

1
2
3
4
5
6
7
8

<!-- Add class after 200ms of loading -->
<div data-loading="delay|addClass(opacity-50)">...</div>

<!-- Show after 200ms of loading -->
<div data-loading="delay|show">Loading</div>

<!-- Show after 500ms of loading -->
<div data-loading="delay(500)|show">Loading</div>

Targeting Loading for a Specific Action

To only toggle the loading behavior when a specific action is triggered, use the action() modifier with the name of the action - e.g. saveForm():

1
2
3
4

<!-- show only when the "saveForm" action is triggering -->
<span data-loading="action(saveForm)|show">Loading</span>
<!-- multiple modifiers -->
<div data-loading="action(saveForm)|delay|addClass(opacity-50)">...</div>

Targeting Loading When a Specific Model Changes

You can also toggle the loading behavior only if a specific model value was just changed using the model() modifier:

1
2
3
4
5
6
7
8

<input data-model="email" type="email">

<span data-loading="model(email)|show">
    Checking if email is available...
</span>

<!-- multiple modifiers & child properties -->
<span data-loading="model(user.email)|delay|addClass(opacity-50)">...</span>

Actions & Services

One really neat thing about component actions is that they are real Symfony controllers. Internally, they are processed identically to a normal controller method that you would create with a route.

This means that, for example, you can use action autowiring:

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

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

// ...
use Psr\Log\LoggerInterface;

class RandomNumberComponent
{
    // ...

    #[LiveAction]
    public function resetMax(LoggerInterface $logger)
    {
        $this->max = 1000;
        $logger->debug('The min/max were reset!');
    }

    // ...
}

Actions & Arguments

You can also provide custom arguments to your action:

1
2
3
4
5
6

<form>
    <button
        data-action="live#action"
        data-action-name="addItem(id={{ item.id }}, itemName=CustomItem)"
    >Add Item</button>
</form>

In your component, to allow each argument to be passed, we need to add the #[LiveArg()] attribute:

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

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

// ...
use Symfony\UX\LiveComponent\Attribute\LiveArg;
use Psr\Log\LoggerInterface;

class ItemComponent
{
    // ...
    #[LiveAction]
    public function addItem(#[LiveArg] int $id, #[LiveArg('itemName')] string $name)
    {
        $this->id = $id;
        $this->name = $name;
    }
}

Normally, the argument name in PHP - e.g. $id - should match the argument named used in Twig id={{ item.id }}. But if they don't match, you can pass an argument to LiveArg, like we did with itemName.

Actions and CSRF Protection

When you trigger an action, a POST request is sent that contains a X-CSRF-TOKEN header. This header is automatically populated and validated. In other words… you get CSRF protection without any work.

Your only job is to make sure that the CSRF component is installed:

1

$ composer require symfony/security-csrf

If you want to disable CSRF for a single component you can set csrf option to false:

1
2
3
4
5
6
7
8
9
10

namespace App\Twig\Components;

use Symfony\UX\LiveComponent\Attribute\AsLiveComponent;
use Symfony\UX\LiveComponent\Attribute\LiveProp;

#[AsLiveComponent('my_live_component', csrf: false)]
class MyLiveComponent
{
    // ...
}

Actions, Redirecting and AbstractController

Sometimes, you may want to redirect after an action is executed (e.g. your action saves a form and then you want to redirect to another page). You can do that by returning a RedirectResponse from your action:

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

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

// ...
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;

class RandomNumberComponent extends AbstractController
{
    // ...

    #[LiveAction]
    public function resetMax()
    {
        // ...

        $this->addFlash('success', 'Max has been reset!');

        return $this->redirectToRoute('app_random_number');
    }

    // ...
}

You probably noticed one interesting trick: to make redirecting easier, the component now extends AbstractController! That is totally allowed, and gives you access to all of your normal controller shortcuts. We even added a flash message!

Rendering an Entire Form in a Component

Suppose you have a PostType form class that's bound to a Post entity and you'd like to render this in a component so that you can get instant validation as the user types:

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

namespace App\Form;

use App\Entity\Post;
use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\FormBuilderInterface;
use Symfony\Component\OptionsResolver\OptionsResolver;

class PostType extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options)
    {
        $builder
            ->add('title')
            ->add('slug')
            ->add('content')
        ;
    }

    public function configureOptions(OptionsResolver $resolver)
    {
        $resolver->setDefaults([
            'data_class' => Post::class,
        ]);
    }
}

Before you start thinking about the component, make sure that you have your controller set up so you can handle the form submit. There's nothing special about this controller: it's written however you normally write your form controller logic:

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

namespace App\Controller;

use App\Entity\Post;
use App\Form\PostType;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;

class PostController extends AbstractController
{
    /**
     * #[Route('/admin/post/{id}/edit', name: 'app_post_edit')]
     */
    public function edit(Request $request, Post $post, EntityManagerInterface $entityManager): Response
    {
        $form = $this->createForm(PostType::class, $post);
        $form->handleRequest($request);

        if ($form->isSubmitted() && $form->isValid()) {
            $entityManager->flush();

            return $this->redirectToRoute('app_post_index');
        }

        return $this->render('post/edit.html.twig', [
            'post' => $post,
            'form' => $form,
        ]);
    }
}

Great! In the template, instead of rendering the form, let's render a post_form component that we will create next:

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

{# templates/post/edit.html.twig #}

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

{% block body %}
    <h1>Edit Post</h1>

    {{ component('post_form', {
        post: post,
        form: form
    }) }}
{% endblock %}

Ok: time to build that post_form component! The Live Components package comes with a special trait - ComponentWithFormTrait - to make it easy to deal with forms:

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

namespace App\Twig\Components;

use App\Entity\Post;
use App\Form\PostType;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\Form\FormInterface;
use Symfony\UX\LiveComponent\Attribute\AsLiveComponent;
use Symfony\UX\LiveComponent\Attribute\LiveProp;
use Symfony\UX\LiveComponent\ComponentWithFormTrait;
use Symfony\UX\LiveComponent\DefaultActionTrait;

#[AsLiveComponent('post_form')]
class PostFormComponent extends AbstractController
{
    use DefaultActionTrait;
    use ComponentWithFormTrait;

    /**
     * The initial data used to create the form.
     *
     * Needed so the same form can be re-created
     * when the component is re-rendered via Ajax.
     *
     * The `fieldName` option is needed in this situation because
     * the form renders fields with names like `name="post[title]"`.
     * We set `fieldName: ''` so that this live prop doesn't collide
     * with that data. The value - data - could be anything.
     */
    #[LiveProp(fieldName: 'data')]
    public ?Post $post = null;

    /**
     * Used to re-create the PostType form for re-rendering.
     */
    protected function instantiateForm(): FormInterface
    {
        // we can extend AbstractController to get the normal shortcuts
        return $this->createForm(PostType::class, $this->post);
    }
}

The trait forces you to create an instantiateForm() method, which is used when the component is rendered via AJAX. Notice that, in order to recreate the same form, we pass in the Post object and set it as a LiveProp.

The template for this component will render the form, which is available as form thanks to the trait:

1
2
3
4
5
6
7
8
9
10

{# templates/components/post_form.html.twig #}
<div {{ attributes }}>
    {{ form_start(form) }}
        {{ form_row(form.title) }}
        {{ form_row(form.slug) }}
        {{ form_row(form.content) }}

        <button>Save</button>
    {{ form_end(form) }}
</div>

That's a pretty boring template! It includes the normal attributes and then you render the form however you want.

But the result is incredible! As you finish changing each field, the component automatically re-renders - including showing any validation errors for that field! Amazing!

This is possible thanks to the team work of two pieces:

• ComponentWithFormTrait adds a data-model="on(change)|*" attribute to your <form> tag. This causes each field to become a "model" that will update on "change" (override the getDataModelValue() method to control this). See "Live Components".
• ComponentWithFormTrait has a modifiable LiveProp that holds the form data and is updated each time a field changes. On each re-render, these values are used to "submit" the form, triggering validation! However, if a field has not been modified yet by the user, its validation errors are cleared so that they aren't displayed.

Handling "Cannot dehydrate an unpersisted entity" Errors.

If you're building a form to create a new entity, then when you render the component, you may be passing a new, non-persisted entity, to your component:

1
2
3
4
5
6
7
8

{# templates/post/new.html.twig #}

<h1>Create new Post</h1>

{{ component('post_form', {
    post: post,
    form: form
}) }}

If you do this, you'll likely see this error:

Cannot dehydrate an unpersisted entity App\Entity\Post. If you want to allow this, add a dehydrateWith= option to LiveProp

The problem is that the Live component system doesn't know how to transform this object into something that can be sent to the frontend, called "dehydration". If an entity has already been saved to the database, its "id" is sent to the frontend. But if the entity hasn't been saved yet, that's not possible.

The solution is to pass null to your component instead of a non-persisted entity object:

1
2
3
4
5

{{ component('post_form', {
-     post: post,
+     post: post.id ? post : null,
      form: form
  }) }}

If you need to (e.g. to render the form with default values), you can re-create your new Post() inside of your component's createForm() method before calling createForm().

Form Rendering Problems

For the most part, rendering a form inside a component works beautifully. But there are a few situations when your form may not behave how you want.

A) Text Boxes Removing Trailing Spaces

If you're re-rendering a field on the input event (that's the default event on a field, which is fired each time you type in a text box), then if you type a "space" and pause for a moment, the space will disappear!

This is because Symfony text fields "trim spaces" automatically. When your component re-renders, the space will disappear… as the user is typing! To fix this, either re-render on the change event (which fires after the text box loses focus) or set the trim option of your field to false:

1
2
3
4
5
6
7
8
9

public function buildForm(FormBuilderInterface $builder, array $options)
{
    $builder
        // ...
        ->add('content', TextareaType::class, [
            'trim' => false,
        ])
    ;
}

B) PasswordType loses the password on re-render

If you're using the PasswordType, when the component re-renders, the input will become blank! That's because, by default, the PasswordType does not re-fill the <input type="password"> after a submit.

To fix this, set the always_empty option to false in your form:

1
2
3
4
5
6
7
8
9

public function buildForm(FormBuilderInterface $builder, array $options)
{
    $builder
        // ...
        ->add('plainPassword', PasswordType::class, [
            'always_empty' => false,
        ])
    ;
}

Submitting the Form via an action()

Notice that, while we could add a save() component action that handles the form submit through the component, we've chosen not to do that so far. The reason is simple: by creating a normal route & controller that handles the submit, our form continues to work without JavaScript.

However, you can do this if you'd like. In that case, you wouldn't need any form logic in your controller:

1
2
3
4
5
6
7

#[Route('/admin/post/{id}/edit', name: 'app_post_edit')]
public function edit(Post $post): Response
{
    return $this->render('post/edit.html.twig', [
        'post' => $post,
    ]);
}

And you wouldn't pass any form into the component:

1
2
3
4
5
6
7

{# templates/post/edit.html.twig #}

<h1>Edit Post</h1>

{{ component('post_form', {
    post: post
}) }}

When you do not pass a form into a component that uses ComponentWithFormTrait, the form will be created for you automatically. Let's add the save() action to the component:

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

// ...
use Doctrine\ORM\EntityManagerInterface;
use Symfony\UX\LiveComponent\Attribute\LiveAction;

class PostFormComponent extends AbstractController
{
    // ...

    #[LiveAction]
    public function save(EntityManagerInterface $entityManager)
    {
        // shortcut to submit the form with form values
        // if any validation fails, an exception is thrown automatically
        // and the component will be re-rendered with the form errors
        $this->submitForm();

        /** @var Post $post */
        $post = $this->getFormInstance()->getData();
        $entityManager->persist($post);
        $entityManager->flush();

        $this->addFlash('success', 'Post saved!');

        return $this->redirectToRoute('app_post_show', [
            'id' => $this->post->getId(),
        ]);
    }
}

Finally, tell the form element to use this action:

1
2
3
4
5
6
7
8
9

{# templates/components/post_form.html.twig #}
{# ... #}

{{ form_start(form, {
    attr: {
        'data-action': 'live#action',
        'data-action-name': 'prevent|save'
    }
}) }}

Now, when the form is submitted, it will execute the save() method via Ajax. If the form fails validation, it will re-render with the errors. And if it's successful, it will redirect.

Using Actions to Change your Form: CollectionType

Symfony's CollectionType can be used to embed a collection of embedded forms including allowing the user to dynamically add or remove them. Live components make this all possible while writing zero JavaScript.

For example, imagine a "Blog Post" form with an embedded "Comment" forms via the CollectionType:

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

namespace App\Form;

use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\Extension\Core\Type\CollectionType;
use Symfony\Component\Form\FormBuilderInterface;
use Symfony\Component\OptionsResolver\OptionsResolver;
use App\Entity\BlogPost;

class BlogPostFormType extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options)
    {
        $builder
            ->add('title', TextType::class)
            // ...
            ->add('comments', CollectionType::class, [
                'entry_type' => CommentFormType::class,
                'allow_add' => true,
                'allow_delete' => true,
                'by_reference' => false,
            ])
        ;
    }

    public function configureOptions(OptionsResolver $resolver)
    {
        $resolver->setDefaults(['data_class' => BlogPost::class]);
    }
}

Now, create a Twig component to render the form:

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

namespace App\Twig;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\Form\FormInterface;
use Symfony\UX\LiveComponent\Attribute\AsLiveComponent;
use Symfony\UX\LiveComponent\Attribute\LiveAction;
use Symfony\UX\LiveComponent\ComponentWithFormTrait;
use Symfony\UX\LiveComponent\DefaultActionTrait;
use App\Entity\BlogPost;
use App\Entity\Comment;
use App\Form\BlogPostFormType;

#[AsLiveComponent('blog_post_collection_type')]
class BlogPostCollectionTypeComponent extends AbstractController
{
    use ComponentWithFormTrait;
    use DefaultActionTrait;

    #[LiveProp]
    public BlogPost $post;

    protected function instantiateForm(): FormInterface
    {
        return $this->createForm(BlogPostFormType::class, $this->post);
    }

    #[LiveAction]
    public function addComment()
    {
        // "formValues" represents the current data in the form
        // this modifies the form to add an extra comment
        // the result: another embedded comment form!
        // change "comments" to the name of the field that uses CollectionType
        $this->formValues['comments'][] = [];
    }

    #[LiveAction]
    public function removeComment(#[LiveArg] int $index)
    {
        unset($this->formValues['comments'][$index]);
    }
}

The template for this component has two jobs: (1) render the form like normal and (2) include links that trigger the addComment() and removeComment() actions:

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

<div{{ attributes }}>
    {{ form_start(form) }}
        {{ form_row(form.title) }}

        <h3>Comments:</h3>
        {% for key, commentForm in form.comments %}
            <button
                data-action="live#action"
                data-action-name="removeComment(index={{ key }})"
                type="button"
            >X</button>

            {{ form_widget(commentForm) }}
        {% endfor %}
        </div>

        {# avoid an extra label for this field #}
        {% do form.comments.setRendered %}

        <button
            data-action="live#action"
            data-action-name="addComment"
            type="button"
        >+ Add Comment</button>

        <button type="submit" >Save</button>
    {{ form_end(form) }}
</div>

Done! Behind the scenes, it works like this:

A) When the user clicks "+ Add Comment", an Ajax request is sent that triggers the addComment() action.

B) addComment() modifies formValues, which you can think of as the raw "POST" data of your form.

C) Still during the Ajax request, the formValues are "submitted" into your form. The new key inside of $this->formValues['comments'] tells the CollectionType that you want a new, embedded form.

D) The form is rendered - now with another embedded form! - and the Ajax call returns with the form (with the new embedded form).

When the user clicks removeComment(), a similar process happens.

Using LiveCollectionType

The LiveCollectionType uses the same method described above, but in a generic way, so it needs even less code. This form type adds an 'Add' and a 'Delete' button for each row by default, which work out of the box thanks to the LiveCollectionTrait.

Let's take the same example as before, a "Blog Post" form with an embedded "Comment" forms via the LiveCollectionType:

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

namespace App\Form;

use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\FormBuilderInterface;
use Symfony\Component\OptionsResolver\OptionsResolver;
use Symfony\UX\LiveComponent\Form\Type\LiveCollectionType;
use App\Entity\BlogPost;

class BlogPostFormType extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options)
    {
        $builder
            ->add('title', TextType::class)
            // ...
            ->add('comments', LiveCollectionType::class, [
                'entry_type' => CommentFormType::class,
            ])
        ;
    }

    public function configureOptions(OptionsResolver $resolver)
    {
        $resolver->setDefaults(['data_class' => BlogPost::class]);
    }
}

Now, create a Twig component to render the form:

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

namespace App\Twig;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\Form\FormInterface;
use Symfony\UX\LiveComponent\Attribute\AsLiveComponent;
use Symfony\UX\LiveComponent\DefaultActionTrait;
use Symfony\UX\LiveComponent\LiveCollectionTrait;
use Symfony\UX\LiveComponent\Attribute\LiveProp;
use App\Entity\BlogPost;
use App\Form\BlogPostFormType;

#[AsLiveComponent('blog_post_collection_type')]
class BlogPostCollectionTypeComponent extends AbstractController
{
    use LiveCollectionTrait;
    use DefaultActionTrait;

    #[LiveProp]
    public BlogPost $post;

    protected function instantiateForm(): FormInterface
    {
        return $this->createForm(BlogPostFormType::class, $this->post);
    }
}

There is no need for a custom template just render the form as usual:

1
2
3

<div {{ attributes }}>
    {{ form(form) }}
</div>

This automatically renders add and delete buttons that are connected to the live component. If you want to customize how the buttons and the collection rows are rendered, you can use Symfony's built-in form theming techniques, but you should note that, the buttons are not part of the form tree.

Here are some examples of these techniques.

If you only want to customize some attributes, the simplest to use the options in the form type:

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

// ...
->add('comments', LiveCollectionType::class, [
    'entry_type' => CommentFormType::class,
    'label' => false,
    'button_delete_options' => [
        'label' => 'X',
        'attr' => [
            'class' => 'btn btn-outline-danger',
        ],
    ]
])
// ...

Inline rendering:

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

<div {{ attributes }}>
    {{ form_start(form) }}
        {{ form_row(form.title)

        <h3>Comments:</h3>
        {% for key, commentForm in form.comments %}
            {# render a delete button for every row #}
            {{ form_row(commentForm.vars.button_delete, { label: 'X', attr: { class: 'btn btn-outline-danger' } }) }}

            {# render rest of the comment form #}
            {{ form_row(commentForm, { label: false }) }}
        {% endfor %}

        {# render the add button #}
        {{ form_widget(form.comments.vars.button_add_prototype, { label: '+ Add comment', class: 'btn btn-outline-primary' }) }}

        {# render rest of the form #}
        {{ form_row(form) }}

        <button type="submit" >Save</button>
    {{ form_end(form) }}
</div>

Override the specific block for comment items:

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

{% form_theme form 'components/_form_theme_comment_list.html.twig' %}

<div {{ attributes }}>
    {{ form_start(form) }}

    {{ form_start(form) }}
        {{ form_row(form.title)

        <h3>Comments:</h3>
        <ul>
            {{ form_row(form.comments, { skip_add_button: true }) }}
        </ul>

        {# render rest of the form #}
        {{ form_row(form) }}

        <button type="submit" >Save</button>
    {{ form_end(form) }}
</div>

1
2
3
4
5
6
7

{# components/_form_theme_comment_list.html.twig #}
{%- block _blog_post_form_comments_entry_row -%}
    <li class="...">
        {{ form_row(form.content, { label: false }) }}
        {{ form_row(button_delete_prototype, { label: 'X', attr: { class: 'btn btn-outline-danger' } }) }}
    </li>
{% endblock %}

Override the generic buttons and collection entry:

The add and delete buttons are rendered as separate ButtonType form types and can be customized like a normal form type via the live_collection_button_add and live_collection_button_delete block prefix respectively:

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

{% block live_collection_button_add_widget %}
    {% set attr = attr|merge({'class': attr.class|default('btn btn-ghost')}) %}
    {% set translation_domin = false %}
    {% set label_html = true %}
    {%- set label -%}
        <svg xmlns="http://www.w3.org/2000/svg" class="h-6 w-6" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2">
            <path stroke-linecap="round" stroke-linejoin="round" d="M12 6v6m0 0v6m0-6h6m-6 0H6" />
        </svg>
        {{ 'form.collection.button.add.label'|trans({}, 'forms') }}
    {%- endset -%}
    {{ block('button_widget') }}
{% endblock live_collection_button_add_widget %}

To control how each row is rendered you can override the blocks related to the LiveCollectionType. This works the same way as the traditional collection type, but you should use live_collection_* and live_collection_entry_* as prefixes instead.

For example, by default the add button is placed after the items (the comments in our case). Let's move it before them.

1
2
3
4
5
6

{%- block live_collection_widget -%}
    {%- if button_add is defined and not button_add.rendered -%}
        {{ form_row(button_add) }}
    {%- endif -%}
    {{ block('form_widget') }}
{%- endblock -%}

Now add a div around each row:

1
2
3
4
5
6
7
8

{%- block live_collection_entry_row -%}
    <div>
        {{ block('form_row') }}
        {%- if button_delete is defined and not button_delete.rendered -%}
            {{ form_row(button_delete) }}
        {%- endif -%}
    </div>
{%- endblock -%}

As another example, let's create a general bootstrap 5 theme for the live collection type, rendering every item in a table row:

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

{%- block live_collection_widget -%}
    <table class="table table-borderless form-no-mb">
        <thead>
        <tr>
            {% for child in form|last %}
                <td>{{ form_label(child) }}</td>
            {% endfor %}
            <td></td>
        </tr>
        </thead>
        <tbody>
            {{ block('form_widget') }}
        </tbody>
    </table>
    {%- if skip_add_button|default(false) is same as(false) and button_add is defined and not button_add.rendered -%}
        {{ form_widget(button_add, { label: '+ Add Item', attr: { class: 'btn btn-outline-primary' } }) }}
    {%- endif -%}
{%- endblock -%}

{%- block live_collection_entry_row -%}
    <tr>
        {% for child in form %}
            <td>{{- form_row(child, { label: false }) -}}</td>
        {% endfor %}
        <td>
            {{- form_row(button_delete, { label: 'X', attr: { class: 'btn btn-outline-danger' } }) -}}
        </td>
    </tr>
{%- endblock -%}

To render the add button later in the template, you can skip rendering it initially with skip_add_button, then render it manually after:

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

<table class="table table-borderless form-no-mb">
    <thead>
        <tr>
            <td>Item</td>
            <td>Priority</td>
            <td></td>
        </tr>
    </thead>
    <tbody>
        {{ form_row(form.todoItems, { skip_add_button: true }) }}
    </tbody>
</table>

{{ form_widget(form.todoItems.vars.button_add, { label: '+ Add Item', attr: { class: 'btn btn-outline-primary' } }) }}

Validation (without a Form)

If you're building a form without using Symfony's form component, you can still validate your data.

First use the ValidatableComponentTrait and add any constraints you need:

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

use App\Entity\User;
use Symfony\UX\LiveComponent\Attribute\AsLiveComponent;
use Symfony\UX\LiveComponent\Attribute\LiveProp;
use Symfony\UX\LiveComponent\ValidatableComponentTrait;
use Symfony\Component\Validator\Constraints as Assert;

#[AsLiveComponent('edit_user')]
class EditUserComponent
{
    use ValidatableComponentTrait;

    #[LiveProp(exposed: ['email', 'plainPassword'])]
    #[Assert\Valid]
    public User $user;

     #[LiveProp]
     #[Assert\IsTrue]
    public bool $agreeToTerms = false;
}

Be sure to add the IsValid attribute/annotation to any property where you want the object on that property to also be validated.

Thanks to this setup, the component will now be automatically validated on each render, but in a smart way: a property will only be validated once its "model" has been updated on the frontend. The system keeps track of which models have been updated and only stores the errors for those fields on re-render.

You can also trigger validation of your entire object manually in an action:

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

use Symfony\UX\LiveComponent\Attribute\LiveAction;

#[AsLiveComponent('edit_user')]
class EditUserComponent
{
    // ...

    #[LiveAction]
    public function save()
    {
        // this will throw an exception if validation fails
        $this->validate();

        // perform save operations
    }
}

If validation fails, an exception is thrown, but the component will be re-rendered. In your template, render errors using the getError() method:

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

{% if this.getError('post.content') %}
    <div class="error">
        {{ this.getError('post.content').message }}
    </div>
{% endif %}
<textarea
    data-model="post.content"
    class="{{ this.getError('post.content') ? 'has-error' : '' }}"
></textarea>

{% if this.getError('agreeToTerms') %}
    <div class="error">
        {{ this.getError('agreeToTerms').message }}
    </div>
{% endif %}
<input type="checkbox" data-model="agreeToTerms" class="{{ this.getError('agreeToTerms') ? 'has-error' : '' }}"/>

<button
    type="submit"
    data-action="live#action"
    data-action-name="prevent|save"
>Save</button>

Once a component has been validated, the component will "remember" that it has been validated. This means that, if you edit a field and the component re-renders, it will be validated again.

Real-Time Validation on Change

As soon as validation is enabled, each field will be validated the moment that its model is updated. By default, that happens in the input event, so when the user types into text fields. Often, that's too much (e.g. you want a user to finish typing their full email address before validating it).

To validate only on "change", use the on(change) modifier:

1
2
3
4
5

<input
    type="email"
    data-model="on(change)|user.email"
    class="{{ this.getError('post.content') ? 'has-error' : '' }}"
>

Each component re-renders independent of one another

If a parent component re-renders, this may or may not cause the child component to send its own Ajax request to re-render. What determines that? Let's look at an example of a todo list component with a child that renders the total number of todo items:

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

{# templates/components/todo_list.html.twig #}
<div {{ attributes }}>
    <input data-model="listName">

    {% for todo in todos %}
        ...
    {% endfor %}

    {{ component('todo_footer', {
        count: todos|length
    }) }}
</div>

Suppose the user updates the listName model and the parent component re-renders. In this case, the child component will not re-render. Why? Because the live components system will detect that none of the values passed into todo_footer (just count in this case). Have change. If no inputs to the child changed, there's no need to re-render it.

But if the user added a new todo item and the number of todos changed from 5 to 6, this would change the count value that's passed into the todo_footer. In this case, immediately after the parent component re-renders, the child request will make a second Ajax request to render itself. Smart!

Child components keep their modifiable LiveProp values

But suppose that the todo_footer in the previous example also has an isVisible LiveProp(writable: true) property which starts as true but can be changed (via a link click) to false. Will re-rendering the child cause this to be reset back to its original value? Nope! When the child component re-renders, it will keep the current value for any of its writable props.

What if you do want your entire child component to re-render (including resetting writable live props) when some value in the parent changes? This can be done by manually giving your component a data-live-id attribute that will change if the component should be totally re-rendered:

1
2
3
4
5
6
7
8
9

{# templates/components/todo_list.html.twig #}
<div {{ attributes }}>
    <!-- ... -->

    {{ component('todo_footer', {
        count: todos|length,
        'data-live-id': 'todo-footer-'~todos|length
    }) }}
</div>

In this case, if the number of todos change, then the data-live-id attribute of the component will also change. This signals that the component should re-render itself completely, discarding any writable LiveProp values.

Actions in a child do not affect the parent

Again, each component is its own, isolated universe! For example, suppose your child component has:

1

<button data-action="live#action" data-action-name="save">Save</button>

When the user clicks that button, it will attempt to call the save action in the child component only, even if the save action actually only exists in the parent. The same is true for data-model, though there is some special handling for this case (see next point).

Updating a Parent Model from a Child

Suppose a child component has a:

1

<textarea data-model="value">

When the user changes this field, this will only update the value field in the child component… because (yup, we're saying it again): each component is its own, isolated universe.

However, sometimes this isn't what you want! Sometimes, when a child model changes, that should also update a model on the parent. To do this, pass a dataModel (or data-model) attribute to the child:

1
2
3
4
5
6

{# templates/components/post_form.html.twig #}

{{ component('textarea_field', {
    dataModel: 'value:content',
    error: this.getError('content'),
}) }}

This does two things:

1. A prop called value will be passed into textarea_field set to content from the parent component (i.e. the same as manually passing value: content into the component).
2. When the value prop changes inside of textarea_field, the content prop will change on the parent component.

This result is that, when value changes, the parent component will also re-render, thanks to the fact that its content prop changed.

If the child component model is called value, you can also shorten the syntax:

1
2
3
4

<!-- same as "value:content" -->
{{ component('textarea_field', {
    dataModel: 'content',
}) }}

If your child component has multiple models, separate each with a space:

1
2
3

{{ component('textarea_field', {
    dataModel: 'user.firstName:first user.lastName:last',
}) }}

In this case, the child component will receive first and last props. And, when those update, the user.firstName and user.lastName models will be updated on the parent.

Full Embedded Component Example

Let's look at a full, complex example of an embedded component. Suppose you have an EditPostComponent:

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

namespace App\Twig\Components;

use App\Entity\Post;
use Doctrine\ORM\EntityManagerInterface;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\UX\LiveComponent\Attribute\AsLiveComponent;
use Symfony\UX\LiveComponent\Attribute\LiveAction;
use Symfony\UX\LiveComponent\Attribute\LiveProp;

#[AsLiveComponent('edit_post')]
final class EditPostComponent extends AbstractController
{
    #[LiveProp(exposed: ['title', 'content'])]
    public Post $post;

    #[LiveAction]
    public function save(EntityManagerInterface $entityManager)
    {
        $entityManager->flush();

        return $this->redirectToRoute('some_route');
    }
}

And a MarkdownTextareaComponent:

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

namespace App\Twig\Components;

use Symfony\UX\LiveComponent\Attribute\AsLiveComponent;
use Symfony\UX\LiveComponent\Attribute\LiveProp;

#[AsLiveComponent('markdown_textarea')]
final class MarkdownTextareaComponent
{
    #[LiveProp]
    public string $label;

    #[LiveProp]
    public string $name;

    #[LiveProp(writable: true)]
    public string $value = '';
}

In the EditPostComponent template, you render the MarkdownTextareaComponent:

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

{# templates/components/edit_post.html.twig #}
<div {{ attributes }}>
    <form data-model="on(change)|*">
        <input
            type="text"
            name="post[title]"
            value="{{ post.title }}"
        >

        {{ component('markdown_textarea', {
            name: 'post[content]',
            dataModel: 'value:post.content',
            label: 'Content',
        }) }}

        <button
            data-action="live#action"
            data-action-name="save"
        >Save</button>
    </form>
</div>

1
2
3
4
5
6
7
8
9
10

<div {{ attributes }} class="mb-3">
    <textarea
        name="{{ name }}"
        data-model="value"
    ></textarea>

    <div class="markdown-preview">
        {{ value|markdown_to_html }}
    </div>
</div>

Notice that MarkdownTextareaComponent allows a dynamic name attribute to be passed in. This makes that component re-usable in any form.

Rendering Quirks with List of Embedded Components

Imagine your component renders a list of embedded components and that list is updated as the user types into a search box. Most of the time, this works fine. But in some cases, as the list of items changes, a child component will re-render even though it was there before and after the list changed. This can cause that child component to lose some state (i.e. it re-renders with its original live props data).

To fix this, add a unique data-live-id attribute to the root component of each child element. This will helps LiveComponent identify each item in the list and correctly determine if a re-render is necessary, or not.