.. index:: single: Forms; Fields; ChoiceType ChoiceType Field (select drop-downs, radio buttons & checkboxes) ================================================================ A multi-purpose field used to allow the user to "choose" one or more options. It can be rendered as a ``select`` tag, radio buttons, or checkboxes. To use this field, you must specify *either* ``choices`` or ``choice_loader`` option. +-------------+------------------------------------------------------------------------------+ | Rendered as | can be various tags (see below) | +-------------+------------------------------------------------------------------------------+ | Options | - `choices`_ | | | - `choice_attr`_ | | | - `choice_filter`_ | | | - `choice_label`_ | | | - `choice_loader`_ | | | - `choice_name`_ | | | - `choice_translation_domain`_ | | | - `choice_value`_ | | | - `expanded`_ | | | - `group_by`_ | | | - `multiple`_ | | | - `placeholder`_ | | | - `preferred_choices`_ | +-------------+------------------------------------------------------------------------------+ | Overridden | - `compound`_ | | options | - `empty_data`_ | | | - `error_bubbling`_ | | | - `trim`_ | +-------------+------------------------------------------------------------------------------+ | Inherited | - `attr`_ | | options | - `by_reference`_ | | | - `data`_ | | | - `disabled`_ | | | - `error_mapping`_ | | | - `help`_ | | | - `help_attr`_ | | | - `help_html`_ | | | - `inherit_data`_ | | | - `label`_ | | | - `label_attr`_ | | | - `label_format`_ | | | - `mapped`_ | | | - `required`_ | | | - `row_attr`_ | | | - `translation_domain`_ | | | - `label_translation_parameters`_ | | | - `attr_translation_parameters`_ | | | - `help_translation_parameters`_ | +-------------+------------------------------------------------------------------------------+ | Parent type | :doc:`FormType ` | +-------------+------------------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\ChoiceType` | +-------------+------------------------------------------------------------------------------+ .. include:: /reference/forms/types/options/_debug_form.rst.inc Example Usage ------------- The easiest way to use this field is to define the ``choices`` option to specify the choices as an associative array where the keys are the labels displayed to end users and the array values are the internal values used in the form field:: use Symfony\Component\Form\Extension\Core\Type\ChoiceType; // ... $builder->add('isAttending', ChoiceType::class, [ 'choices' => [ 'Maybe' => null, 'Yes' => true, 'No' => false, ], ]); This will create a ``select`` drop-down like this: .. image:: /_images/reference/form/choice-example1.png :align: center If the user selects ``No``, the form will return ``false`` for this field. Similarly, if the starting data for this field is ``true``, then ``Yes`` will be auto-selected. In other words, the **choice** of each item is the value you want to get/set in PHP code, while the **key** is the **label** that will be shown to the user. Advanced Example (with Objects!) -------------------------------- This field has a *lot* of options and most control how the field is displayed. In this example, the underlying data is some ``Category`` object that has a ``getName()`` method:: use App\Entity\Category; use Symfony\Component\Form\Extension\Core\Type\ChoiceType; // ... $builder->add('category', ChoiceType::class, [ 'choices' => [ new Category('Cat1'), new Category('Cat2'), new Category('Cat3'), new Category('Cat4'), ], // "name" is a property path, meaning Symfony will look for a public // property or a public method like "getName()" to define the input // string value that will be submitted by the form 'choice_value' => 'name', // a callback to return the label for a given choice // if a placeholder is used, its empty value (null) may be passed but // its label is defined by its own "placeholder" option 'choice_label' => function(?Category $category) { return $category ? strtoupper($category->getName()) : ''; }, // returns the html attributes for each option input (may be radio/checkbox) 'choice_attr' => function(?Category $category) { return $category ? ['class' => 'category_'.strtolower($category->getName())] : []; }, // every option can use a string property path or any callable that get // passed each choice as argument, but it may not be needed 'group_by' => function() { // randomly assign things into 2 groups return rand(0, 1) == 1 ? 'Group A' : 'Group B'; }, // a callback to return whether a category is preferred 'preferred_choices' => function(?Category $category) { return $category && 100 < $category->getArticleCounts(); }, ]); You can also customize the `choice_name`_ of each choice. You can learn more about all of these options in the sections below. .. caution:: The *placeholder* is a specific field, when the choices are optional the first item in the list must be empty, so the user can unselect. Be sure to always handle the empty choice ``null`` when using callbacks. .. _forms-reference-choice-tags: .. include:: /reference/forms/types/options/select_how_rendered.rst.inc Customizing each Option's Text (Label) -------------------------------------- Normally, the array key of each item in the ``choices`` option is used as the text that's shown to the user. But that can be completely customized via the `choice_label`_ option. Check it out for more details. .. _form-choices-simple-grouping: Grouping Options ---------------- You can group the ``