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.

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).

{# 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:

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.

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

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)).

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).

This test will check if the current form does not have a parent form view.

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' #}{%ifform.parentisnull%}{{form_errors(form)}}{%endif%}{# DO THIS: this check is always reliable, even if the form defines a field called 'parent' #}{%ifformisrootform%}{{form_errors(form)}}{%endif%}

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.

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

New in version 2.3: The method and action variables were introduced in Symfony 2.3.

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.

max_length

Adds a maxlength HTML attribute to the element. (deprecated as of 2.5, to be
removed in 3.0, use attr["maxlength"] instead)

pattern

Adds a pattern HTML attribute to the element. (deprecated as of 2.5, to be
removed in 3.0, use attr["pattern"] instead)

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.