Twig Template Form Function and Variable Reference

Form Rendering Functions

This reference manual covers all the possible Twig functions available for rendering forms. There are several different functions available and each is responsible for rendering a different part of a form (e.g. labels, errors, widgets, etc).

form(view, variables)

Renders the HTML of a complete form.

1
2

{# render the form and change the submission method #}
{{ form(form, {'method': 'GET'}) }}

You will mostly use this helper for prototyping or if you use custom form themes. If you need more flexibility in rendering the form, you should use the other helpers to render individual parts of the form instead:

1
2
3
4
5
6
7
8

{{ form_start(form) }}
    {{ form_errors(form) }}

    {{ form_row(form.name) }}
    {{ form_row(form.dueDate) }}

    {{ form_row(form.submit, { 'label': 'Submit me' }) }}
{{ form_end(form) }}

form_start(view, variables)

Renders the start tag of a form. This helper takes care of printing the configured method and target action of the form. It will also include the correct enctype property if the form contains upload fields.

1
2

{# render the start tag and change the submission method #}
{{ form_start(form, {'method': 'GET'}) }}

form_end(view, variables)

Renders the end tag of a form.

1

{{ form_end(form) }}

This helper also outputs form_rest() unless you set render_rest to false:

1
2

{# don't render unrendered fields #}
{{ form_end(form, {'render_rest': false}) }}

form_label(view, label, variables)

Renders the label for the given field. You can optionally pass the specific label you want to display as the second argument.

1
2
3
4
5
6
7
8
9

{{ form_label(form.name) }}

{# The two following syntaxes are equivalent #}
{{ form_label(form.name, 'Your Name', {'label_attr': {'class': 'foo'}}) }}

{{ form_label(form.name, null, {
    'label': 'Your name',
    'label_attr': {'class': 'foo'}
}) }}

See "Twig Template Form Function and Variable Reference" to learn about the variables argument.

form_errors(view)

Renders any errors for the given field.

1
2
3
4

{{ form_errors(form.name) }}

{# render any "global" errors #}
{{ form_errors(form) }}

form_widget(view, variables)

Renders the HTML widget of a given field. If you apply this to an entire form or collection of fields, each underlying form row will be rendered.

1
2

{# render a widget, but add a "foo" class to it #}
{{ form_widget(form.name, {'attr': {'class': 'foo'}}) }}

The second argument to form_widget() is an array of variables. The most common variable is attr, which is an array of HTML attributes to apply to the HTML widget. In some cases, certain types also have other template-related options that can be passed. These are discussed on a type-by-type basis. The attributes are not applied recursively to child fields if you're rendering many fields at once (e.g. form_widget(form)).

See "Twig Template Form Function and Variable Reference" to learn more about the variables argument.

form_row(view, variables)

Renders the "row" of a given field, which is the combination of the field's label, errors and widget.

1
2

{# render a field row, but display a label with text "foo" #}
{{ form_row(form.name, {'label': 'foo'}) }}

The second argument to form_row() is an array of variables. The templates provided in Symfony only allow to override the label as shown in the example above.

See "Twig Template Form Function and Variable Reference" to learn about the variables argument.

form_rest(view, variables)

This renders all fields that have not yet been rendered for the given form. It's a good idea to always have this somewhere inside your form as it'll render hidden fields for you and make any fields you forgot to render more obvious (since it'll render the field for you).

1

{{ form_rest(form) }}

form_enctype(view)

If the form contains at least one file upload field, this will render the required enctype="multipart/form-data" form attribute. It's always a good idea to include this in your form tag:

1

<form action="{{ path('form_submit') }}" method="post" {{ form_enctype(form) }}>

Form Tests Reference

Tests can be executed by using the is operator in Twig to create a condition. Read the Twig documentation for more information.

1

<option {% if choice is selectedchoice(value) %} selected="selected"{% endif %} ...>

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

{# DON'T DO THIS: this simple check can't differentiate between a form having
    a parent form view and a form defining a nested form field called 'parent' #}

 {% if form.parent is null %}
     {{ form_errors(form) }}
 {% endif %}

{# DO THIS: this check is always reliable, even if the form defines a field called 'parent' #}

 {% if form is rootform %}
     {{ form_errors(form) }}
 {% endif %}

More about Form Variables

In almost every Twig function above, the final argument is an array of "variables" that are used when rendering that one part of the form. For example, the following would render the "widget" for a field and modify its attributes to include a special class:

1
2

{# render a widget, but add a "foo" class to it #}
{{ form_widget(form.name, { 'attr': {'class': 'foo'} }) }}

The purpose of these variables - what they do & where they come from - may not be immediately clear, but they're incredibly powerful. Whenever you render any part of a form, the block that renders it makes use of a number of variables. By default, these blocks live inside form_div_layout.html.twig.

Look at the form_label as an example:

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

{% block form_label %}
    {% if not compound %}
        {% set label_attr = label_attr|merge({'for': id}) %}
    {% endif %}

    {% if required %}
        {% set label_attr = label_attr|merge({
            'class': (label_attr.class|default('') ~ ' required')|trim
        }) %}
    {% endif %}

    {% if label is empty %}
        {% set label = name|humanize %}
    {% endif %}

    <label
        {% for attrname, attrvalue in label_attr -%}
            {{ attrname }}="{{ attrvalue }}"
        {%- endfor %}
    >
        {{ label|trans({}, translation_domain) }}
    </label>
{% endblock form_label %}

This block makes use of several variables: compound, label_attr, required, label, name and translation_domain. These variables are made available by the form rendering system. But more importantly, these are the variables that you can override when calling form_label() (since in this example, you're rendering the label).

The exact variables available to override depends on which part of the form you're rendering (e.g. label versus widget) and which field you're rendering (e.g. a choice widget has an extra expanded option). If you get comfortable with looking through form_div_layout.html.twig, you'll always be able to see what options you have available.

1
2

{# does **not** work - the variables are not recursive #}
{{ form_widget(form, { 'attr': {'class': 'foo'} }) }}

1
2
3
4

<label for="{{ form.name.vars.id }}"
    class="{{ form.name.vars.required ? 'required' }}">
    {{ form.name.vars.label }}
</label>