.. versionadded:: 5.1

The :class:`Symfony\\Component\\Form\\ChoiceList\\ChoiceList` class has

been introduced in Symfony 5.1, to help configuring choices options.

.. _reference-form-choice-loader:

.. include:: /reference/forms/types/options/choice_loader.rst.inc

.. _reference-form-choice-label:

.. include:: /reference/forms/types/options/choice_label.rst.inc

.. tip::

When defining a custom type, you should use the

:class:`Symfony\\Component\\Form\\ChoiceList\\ChoiceList` class helper::

use App\Entity\Category;

use Symfony\Component\Form\ChoiceList\ChoiceList;

use Symfony\Component\Form\ChoiceList\ChoiceList;

// ...

$builder->add('choices', ChoiceType::class, [

'choice_label' => ChoiceList::attr($this, function (?Category $category) {

return $category ? ['data-uuid' => $category->getUuid()] : [];

}),

]);

See the :ref:`"choice_loader" option documentation <reference-form-choice-loader>`.

.. tip::

When defining a custom type, you should use the

:class:`Symfony\\Component\\Form\\ChoiceList\\ChoiceList` class helper::

use Symfony\Component\Form\ChoiceList\ChoiceList;

// ...

$builder->add('choices', ChoiceType::class, [

'choice_label' => ChoiceList::label($this, 'displayName'),

]);

See the :ref:`"choice_loader" option documentation <reference-form-choice-loader>`.

choice_loader

~~~~~~~~~~~~~

**type**: :class:`Symfony\\Component\\Form\\ChoiceList\\Loader\\ChoiceLoaderInterface`

The ``choice_loader`` can be used to only partially load the choices in cases where

a fully-loaded list is not necessary. This is only needed in advanced cases and

would replace the ``choices`` option.

You can use an instance of :class:`Symfony\\Component\\Form\\ChoiceList\\Loader\\CallbackChoiceLoader`

if you want to take advantage of lazy loading::

use App\StaticClass;

use Symfony\Component\Form\ChoiceList\Loader\CallbackChoiceLoader;

use Symfony\Component\Form\Extension\Core\Type\ChoiceType;

// ...

$builder->add('loaded_choices', ChoiceType::class, [

'choice_loader' => new CallbackChoiceLoader(function() {

return StaticClass::getConstants();

}),

]);

This will cause the call of ``StaticClass::getConstants()`` to not happen if the

request is redirected and if there is no pre set or submitted data. Otherwise

the choice options would need to be resolved thus triggering the callback.

When you're defining a custom choice type that may be reused in many fields

(like entries of a collection) or reused in multiple forms at once, you

should use the :class:`Symfony\\Component\\Form\\ChoiceList\\ChoiceList`

static methods to wrap the loader and make the choice list cacheable for

better performance::

use App\Form\ChoiceList\CustomChoiceLoader;

use App\StaticClass;

use Symfony\Component\Form\AbstractType;

use Symfony\Component\Form\ChoiceList\ChoiceList;

use Symfony\Component\Form\Extension\Core\Type\ChoiceType;

use Symfony\Component\OptionsResolver\Options;

use Symfony\Component\OptionsResolver\OptionsResolver;

class ConstantsType extends AbstractType

{

public static function getExtendedTypes(): iterable

{

return [ChoiceType::class];

}

public function configureOptions(OptionsResolver $resolver)

{

$resolver->setDefaults([

// the example below will create a CallbackChoiceLoader from the callable

'choice_loader' => ChoiceList::lazy($this, function() {

return StaticClass::getConstants();

}),

// you can pass your own loader as well, depending on other options

'some_key' => null,

'choice_loader' => function (Options $options) {

return ChoiceList::loader(

// pass the instance of the type or type extension which is

// currently configuring the choice list as first argument

$this,

// pass the other option to the loader

new CustomChoiceLoader($options['some_key']),

// ensure the type stores a loader per key

// by using the special third argument "$vary"

// an array containing anything that "changes" the loader

[$options['some_key']]

);

},

]);

}

}

of the choice views in the template and is used as part of the field name

.. tip::

When defining a custom type, you should use the

:class:`Symfony\\Component\\Form\\ChoiceList\\ChoiceList` class helper::

use Symfony\Component\Form\ChoiceList\ChoiceList;

// ...

$builder->add('choices', ChoiceType::class, [

'choice_name' => ChoiceList::fieldName($this, 'name'),

]);

See the :ref:`"choice_loader" option documentation <reference-form-choice-loader>`.

.. tip::

When defining a custom type, you should use the

:class:`Symfony\\Component\\Form\\ChoiceList\\ChoiceList` class helper::

use Symfony\Component\Form\ChoiceList\ChoiceList;

// ...

$builder->add('choices', ChoiceType::class, [

'choice_value' => ChoiceList::value($this, 'uuid'),

]);

See the :ref:`"choice_loader" option documentation <reference-form-choice-loader>`.

.. tip::

When defining a custom type, you should use the

:class:`Symfony\\Component\\Form\\ChoiceList\\ChoiceList` class helper::

use Symfony\Component\Form\ChoiceList\ChoiceList;

// ...

$builder->add('choices', ChoiceType::class, [

'group_by' => ChoiceList::groupBy($this, 'category'),

]);

See the :ref:`"choice_loader" option documentation <reference-form-choice-loader>`.

.. tip::

When defining a custom type, you should use the

:class:`Symfony\\Component\\Form\\ChoiceList\\ChoiceList` class helper::

use Symfony\Component\Form\ChoiceList\ChoiceList;

// ...

$builder->add('choices', ChoiceType::class, [

'preferred_choices' => ChoiceList::preferred($this, 'taggedAsFavorite'),

]);

See the :ref:`"choice_loader" option documentation <reference-form-choice-loader>`.