From e55e7cda09565450489232ab9144b752f8fe7e73 Mon Sep 17 00:00:00 2001
From: Yonel Ceruto <yonel.ceruto@scnd.com>
Date: Sun, 13 Oct 2024 15:23:24 -0400
Subject: [PATCH] documenting choice_lazy option

---
 reference/forms/types/choice.rst              |  2 ++
 .../forms/types/options/choice_lazy.rst.inc   | 31 +++++++++++++++++++
 2 files changed, 33 insertions(+)
 create mode 100644 reference/forms/types/options/choice_lazy.rst.inc

diff --git a/reference/forms/types/choice.rst b/reference/forms/types/choice.rst
index 55f2d016001..2d31aac890c 100644
--- 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
new file mode 100644
index 00000000000..db8591a613d
--- /dev/null
+++ b/reference/forms/types/options/choice_lazy.rst.inc
@@ -0,0 +1,31 @@
+``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.
+
+.. versionadded:: 7.2
+
+    The ``choice_lazy`` option was introduced in Symfony 7.2.