Skip to content
  • About
    • What is Symfony?
    • Community
    • News
    • Contributing
    • Support
  • Documentation
    • Symfony Docs
    • Symfony Book
    • Screencasts
    • Symfony Bundles
    • Symfony Cloud
    • Training
  • Services
    • SensioLabs Professional services to help you with Symfony
    • Platform.sh for Symfony Best platform to deploy Symfony apps
    • SymfonyInsight Automatic quality checks for your apps
    • Symfony Certification Prove your knowledge and boost your career
    • Blackfire Profile and monitor performance of your apps
  • Other
  • Blog
  • Download
sponsored by SensioLabs
  1. Home
  2. Documentation
  3. Reference
  4. Twig Template Form Function and Variable Reference
  • Documentation
  • Book
  • Reference
  • Bundles
  • Cloud

Table of Contents

  • Form Rendering Functions
  • form(view, variables)
  • form_start(view, variables)
  • form_end(view, variables)
  • form_label(view, label, variables)
  • form_errors(view)
  • form_widget(view, variables)
  • form_row(view, variables)
  • form_rest(view, variables)
  • Form Tests Reference
    • selectedchoice(selected_value)
  • More about Form Variables
    • Form Variables Reference

Twig Template Form Function and Variable Reference

Edit this page

Warning: You are browsing the documentation for Symfony 3.1, which is no longer maintained.

Read the updated version of this page for Symfony 6.2 (the current stable version).

Twig Template Form Function and Variable Reference

When working with forms in a template, there are two powerful things at your disposal:

  • Functions for rendering each part of a form;
  • Variables for getting any information about any field.

You'll use functions often to render your fields. Variables, on the other hand, are less commonly-used, but infinitely powerful since you can access a fields label, id attribute, errors and anything else about the field.

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 Tests Reference

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

selectedchoice(selected_value)

This test will check if the current choice is equal to the selected_value or if the current choice is in the array (when selected_value is an array).

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

More about Form Variables

Tip

For a full list of variables, see: Twig Template Form Function and Variable Reference.

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.

Tip

Behind the scenes, these variables are made available to the FormView object of your form when the Form component calls buildView() and finishView() on each "node" of your form tree. To see what "view" variables a particular field has, find the source code for the form field (and its parent fields) and look at the above two functions.

Note

If you're rendering an entire form at once (or an entire embedded form), the variables argument will only be applied to the form itself and not its children. In other words, the following will not pass a "foo" class attribute to all of the child fields in the form:

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

Form Variables Reference

The following variables are common to every field type. Certain field types may have even more variables and some variables here only really apply to certain types.

Assuming you have a form variable in your template and you want to reference the variables on the name field, accessing the variables is done by using a public vars property on the FormView object:

  • Twig
  • PHP
1
2
3
4
<label for="{{ form.name.vars.id }}"
    class="{{ form.name.vars.required ? 'required' : '' }}">
    {{ form.name.vars.label }}
</label>
1
2
3
4
<label for="<?php echo $view['form']->get('name')->vars['id'] ?>"
    class="<?php echo $view['form']->get('name')->vars['required'] ? 'required' : '' ?>">
    <?php echo $view['form']->get('name')->vars['label'] ?>
</label>
Variable Usage
form The current FormView instance.
id The id HTML attribute to be rendered.
name The name of the field (e.g. title) - but not the name HTML attribute, which is full_name.
full_name The name HTML attribute to be rendered.
errors An array of any errors attached to this specific field (e.g. form.title.errors). Note that you can't use form.errors to determine if a form is valid, since this only returns "global" errors: some individual fields may have errors. Instead, use the valid option.
submitted Returns true or false depending on whether the whole form is submitted
valid Returns true or false depending on whether the whole form is valid.
value The value that will be used when rendering (commonly the value HTML attribute).
disabled If true, disabled="disabled" is added to the field.
required If true, a required attribute is added to the field to activate HTML5 validation. Additionally, a required class is added to the label.
label The string label that will be rendered.
multipart If true, form_enctype will render enctype="multipart/form-data". This only applies to the root form element.
attr A key-value array that will be rendered as HTML attributes on the field.
label_attr A key-value array that will be rendered as HTML attributes on the label.
compound Whether or not a field is actually a holder for a group of children fields (for example, a choice field, which is actually a group of checkboxes.
block_prefixes An array of all the names of the parent types.
translation_domain The domain of the translations for this form.
cache_key A unique key which is used for caching.
data The normalized data of the type.
method The method of the current form (POST, GET, etc.).
action The action of the current form.
This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.
TOC
    Version
    We stand with Ukraine.
    Version:
    Measure & Improve Symfony Code Performance

    Measure & Improve Symfony Code Performance

    Peruse our complete Symfony & PHP solutions catalog for your web development needs.

    Peruse our complete Symfony & PHP solutions catalog for your web development needs.

    Symfony footer

    ↓ Our footer now uses the colors of the Ukrainian flag because Symfony stands with the people of Ukraine.

    Avatar of Fabien Villepinte, a Symfony contributor

    Thanks Fabien Villepinte for being a Symfony contributor

    8 commits • 186 lines changed

    View all contributors that help us make Symfony

    Become a Symfony contributor

    Be an active part of the community and contribute ideas, code and bug fixes. Both experts and newcomers are welcome.

    Learn how to contribute

    Symfony™ is a trademark of Symfony SAS. All rights reserved.

    • What is Symfony?

      • Symfony at a Glance
      • Symfony Components
      • Case Studies
      • Symfony Releases
      • Security Policy
      • Logo & Screenshots
      • Trademark & Licenses
      • symfony1 Legacy
    • Learn Symfony

      • Symfony Docs
      • Symfony Book
      • Reference
      • Bundles
      • Best Practices
      • Training
      • eLearning Platform
      • Certification
    • Screencasts

      • Learn Symfony
      • Learn PHP
      • Learn JavaScript
      • Learn Drupal
      • Learn RESTful APIs
    • Community

      • SymfonyConnect
      • Support
      • How to be Involved
      • Code of Conduct
      • Events & Meetups
      • Projects using Symfony
      • Downloads Stats
      • Contributors
      • Backers
    • Blog

      • Events & Meetups
      • A week of symfony
      • Case studies
      • Cloud
      • Community
      • Conferences
      • Diversity
      • Documentation
      • Living on the edge
      • Releases
      • Security Advisories
      • SymfonyInsight
      • Twig
      • SensioLabs
    • Services

      • SensioLabs services
      • Train developers
      • Manage your project quality
      • Improve your project performance
      • Host Symfony projects

      Deployed on

    Follow Symfony

    Search by Algolia