Refs #32339 -- Added use_fieldset to Widget.

4 files changed, 49 insertions, 0 deletions

diff --git a/docs/ref/forms/api.txt b/docs/ref/forms/api.txt
index e092a2f59e..4d3cf8997d 100644
--- a/docs/ref/forms/api.txt
+++ b/docs/ref/forms/api.txt
@@ -1160,6 +1160,12 @@ Attributes of ``BoundField``
         >>> print(f['message'].name)
         message
 
+.. attribute:: BoundField.use_fieldset
+
+    .. versionadded:: 4.1
+
+    Returns the value of this BoundField widget's ``use_fieldset`` attribute.
+
 .. attribute:: BoundField.widget_type
 
     Returns the lowercased class name of the wrapped field's widget, with any
diff --git a/docs/ref/forms/widgets.txt b/docs/ref/forms/widgets.txt
index 970e30456c..e0f175af79 100644
--- a/docs/ref/forms/widgets.txt
+++ b/docs/ref/forms/widgets.txt
@@ -315,6 +315,19 @@ foundation for custom widgets.
         ``<select multiple>`` don't appear in the data of an HTML form
         submission, so it's unknown whether or not the user submitted a value.
 
+    .. attribute:: Widget.use_fieldset
+
+        .. versionadded:: 4.1
+
+        An attribute to identify if the widget should be grouped in a
+        ``<fieldset>`` with a ``<legend>`` when rendered. Defaults to ``False``
+        but is ``True`` when the widget contains multiple ``<input>`` tags such as
+        :class:`~django.forms.CheckboxSelectMultiple`,
+        :class:`~django.forms.RadioSelect`,
+        :class:`~django.forms.MultiWidget`,
+        :class:`~django.forms.SplitDateTimeWidget`, and
+        :class:`~django.forms.SelectDateWidget`.
+
     .. method:: use_required_attribute(initial)
 
         Given a form field's ``initial`` value, returns whether or not the
diff --git a/docs/releases/4.1.txt b/docs/releases/4.1.txt
index 8fc81e5ee7..7660780ae5 100644
--- a/docs/releases/4.1.txt
+++ b/docs/releases/4.1.txt
@@ -217,6 +217,10 @@ Forms
   objects implement the ``__html__()`` method (typically when decorated with
   the :func:`~django.utils.html.html_safe` decorator).
 
+* The new :attr:`.BoundField.use_fieldset` and :attr:`.Widget.use_fieldset`
+  attributes help to identify widgets where its inputs should be grouped in a
+  ``<fieldset>`` with a ``<legend>``.
+
 Generic Views
 ~~~~~~~~~~~~~
 
diff --git a/docs/topics/forms/index.txt b/docs/topics/forms/index.txt
index d87b9be8d6..2d0d61aa02 100644
--- a/docs/topics/forms/index.txt
+++ b/docs/topics/forms/index.txt
@@ -686,6 +686,32 @@ Useful attributes on ``{{ field }}`` include:
 
         <label for="id_email">Email address:</label>
 
+``{{ field.legend_tag }}``
+
+    .. versionadded:: 4.1
+
+    Similar to ``field.label_tag`` but uses a ``<legend>`` tag in place of
+    ``<label>``, for widgets with multiple inputs wrapped in a ``<fieldset>``.
+
+``{{ field.use_fieldset }}``
+
+    .. versionadded:: 4.1
+
+    This attribute is ``True`` if the form field's widget contains multiple
+    inputs that should be semantically grouped in a ``<fieldset>`` with a
+    ``<legend>`` to improve accessibility. An example use in a template:
+
+.. code-block:: html+django
+
+    {% if field.use_fieldset %}
+      <fieldset>
+      {% if field.label %}{{ field.legend_tag }}{% endif %}
+    {% else %}
+      {% if field.label %}{{ field.label_tag }}{% endif %}
+    {% endif %}
+    {{ field }}
+    {% if field.use_fieldset %}</fieldset>{% endif %}
+
 ``{{ field.value }}``
     The value of the field. e.g ``someone@example.com``.