Fixed #27299 -- Documented the Widget.use_required_attribute() method.

Thanks Tim Graham for the review and edits.

1 files changed, 23 insertions, 0 deletions

diff --git a/docs/ref/forms/widgets.txt b/docs/ref/forms/widgets.txt
index 99514e46a2..c6148a5460 100644
--- a/docs/ref/forms/widgets.txt
+++ b/docs/ref/forms/widgets.txt
@@ -286,6 +286,29 @@ foundation for custom widgets.
         an HTML form submission, so it's unknown whether or not the user
         actually submitted a value.
 
+    .. method:: use_required_attribute(initial)
+
+        .. versionadded:: 1.10.1
+
+        Given a form field's ``initial`` value, returns whether or not the
+        widget can be rendered with the ``required`` HTML attribute. Forms use
+        this method along with :attr:`Field.required
+        <django.forms.Field.required>` and :attr:`Form.use_required_attribute
+        <django.forms.Form.use_required_attribute>` to determine whether or not
+        to display the ``required`` attribute for each field.
+
+        By default, returns ``False`` for hidden widgets and ``True``
+        otherwise. Special cases are :class:`~django.forms.ClearableFileInput`,
+        which returns ``False`` when ``initial`` is not set, and
+        :class:`~django.forms.CheckboxSelectMultiple`, which always returns
+        ``False`` because browser validation would require all checkboxes to be
+        checked instead of at least one.
+
+        Override this method in custom widgets that aren't compatible with
+        browser validation. For example, a WSYSIWG text editor widget backed by
+        a hidden ``textarea`` element may want to always return ``False`` to
+        avoid browser validation on the hidden field.
+
 ``MultiWidget``
 ---------------