documenting choice_lazy option

yceruto · yceruto · commit 481aa693f072 · 2024-10-13T15:23:24.000-04:00
diff --git a/reference/forms/types/choice.rst b/reference/forms/types/choice.rst
@@ -178,6 +178,8 @@ correct types will be assigned to the model.
 
 .. include:: /reference/forms/types/options/choice_loader.rst.inc
 
+.. include:: /reference/forms/types/options/choice_lazy.rst.inc
+
 .. include:: /reference/forms/types/options/choice_name.rst.inc
 
 .. include:: /reference/forms/types/options/choice_translation_domain_enabled.rst.inc
diff --git a/reference/forms/types/options/choice_lazy.rst.inc b/reference/forms/types/options/choice_lazy.rst.inc
@@ -0,0 +1,27 @@
+``choice_lazy``
+~~~~~~~~~~~~~~~
+
+**type**: ``boolean`` **default**: ``false``
+
+The ``choice_lazy`` option is especially useful when dealing with a large set of
+choices, where loading all of them at once could lead to performance issues or
+significant delays::
+
+    use App\Entity\User;
+    use Symfony\Bridge\Doctrine\Form\Type\EntityType;
+
+    $builder->add('user', EntityType::class, [
+        'class' => User::class,
+        'choice_lazy' => true,
+    ]);
+
+When set to ``true``, and used in combination with the ``choice_loader`` option,
+the form will only load and render the choices that are preset as default values
+or submitted. This allows you to defer loading the full list of choices and can
+improve the performance of your form.
+
+.. caution::
+
+    Please note that when using ``choice_lazy``, you are responsible for providing
+    the user interface to select choices, typically through a JavaScript plugin that
+    can handle the dynamic loading of choices.
