From 63c56cda133a85a158502891c40465bc0331d3d9 Mon Sep 17 00:00:00 2001
From: Annabelle Wiegart <annabelle.wiegart@proton.me>
Date: Sun, 18 Jan 2026 20:03:28 +0100
Subject: Fixed #35870 -- Made blank choice label in forms more accessible.

Added new constant django.db.models.fields.BLANK_CHOICE_LABEL for
an accessible and translatable blank choice label in forms.
Deprecated django.db.models.fields.BLANK_CHOICE_DASH constant.
Added the immediately deprecated transitional setting
USE_BLANK_CHOICE_DASH.

Co-Authored-By: Marijke Luttekes <mail@marijkeluttekes.dev>
---
 docs/internals/deprecation.txt |   4 ++++
 docs/intro/_images/admin09.png | Bin 9249 -> 13503 bytes
 docs/ref/forms/fields.txt      |   7 ++++++-
 docs/ref/models/fields.txt     |  15 ++++++++++-----
 docs/ref/settings.txt          |  14 ++++++++++++++
 docs/releases/6.1.txt          |  11 ++++++++++-
 6 files changed, 44 insertions(+), 7 deletions(-)

(limited to 'docs')

diff --git a/docs/internals/deprecation.txt b/docs/internals/deprecation.txt
index 799c355334..c8e467a0ee 100644
--- a/docs/internals/deprecation.txt
+++ b/docs/internals/deprecation.txt
@@ -64,6 +64,10 @@ details on these changes.
   :class:`~django.db.models.JSONNull` to query for a JSON ``null`` value
   instead.
 
+* The ``django.db.models.fields.BLANK_CHOICE_DASH`` constant will be removed.
+
+* The ``USE_BLANK_CHOICE_DASH`` transitional setting will be removed.
+
 * The ``Field.get_placeholder_sql`` shim over the deprecated
   ``get_placeholder`` method will be removed.
 
diff --git a/docs/intro/_images/admin09.png b/docs/intro/_images/admin09.png
index cf2e9a9e1c..5357bb99cf 100644
Binary files a/docs/intro/_images/admin09.png and b/docs/intro/_images/admin09.png differ
diff --git a/docs/ref/forms/fields.txt b/docs/ref/forms/fields.txt
index 73faa8cc18..085b36a0e5 100644
--- a/docs/ref/forms/fields.txt
+++ b/docs/ref/forms/fields.txt
@@ -1384,7 +1384,7 @@ generating choices. See :ref:`iterating-relationship-choices` for details.
 
         By default the ``<select>`` widget used by ``ModelChoiceField`` will
         have an empty choice at the top of the list. You can change the text of
-        this label (which is ``"---------"`` by default) with the
+        this label (which is ``"- Select an option -"`` by default) with the
         ``empty_label`` attribute, or you can disable the empty label entirely
         by setting ``empty_label`` to ``None``::
 
@@ -1400,6 +1400,11 @@ generating choices. See :ref:`iterating-relationship-choices` for details.
         :class:`~django.forms.RadioSelect` and the
         :attr:`~ModelChoiceField.blank` argument is ``False``.
 
+    .. versionchanged:: 6.1
+
+        The default empty label was changed from ``"---------"`` to
+        ``"- Select an option -"``.
+
     .. attribute:: to_field_name
 
         This optional argument is used to specify the field to use as the value
diff --git a/docs/ref/models/fields.txt b/docs/ref/models/fields.txt
index 1cf521d621..4405d91daf 100644
--- a/docs/ref/models/fields.txt
+++ b/docs/ref/models/fields.txt
@@ -224,11 +224,16 @@ documentation.
 .. _field-choices-blank-label:
 
 Unless :attr:`blank=False<Field.blank>` is set on the field along with a
-:attr:`~Field.default` then a label containing ``"---------"`` will be rendered
-with the select box. To override this behavior, add a tuple to ``choices``
-containing ``None``; e.g. ``(None, 'Your String For Display')``.
-Alternatively, you can use an empty string instead of ``None`` where this makes
-sense - such as on a :class:`~django.db.models.CharField`.
+:attr:`~Field.default` then a label containing ``"- Select an option -"`` will
+be rendered with the select box. To override this behavior, add a tuple to
+``choices`` containing ``None``; e.g. ``(None, 'Your String For Display')``.
+Alternatively, you can use an empty string instead of ``None`` where this
+makes sense - such as on a :class:`~django.db.models.CharField`.
+
+.. versionchanged:: 6.1
+
+    The default blank label was changed from ``"---------"`` to
+    ``"- Select an option -"``.
 
 .. _field-choices-enum-types:
 
diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt
index cca7b18f24..c4e2c6f2c3 100644
--- a/docs/ref/settings.txt
+++ b/docs/ref/settings.txt
@@ -3044,6 +3044,19 @@ the correct environment.
 
 .. _list of time zones: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
 
+.. setting:: USE_BLANK_CHOICE_DASH
+
+``USE_BLANK_CHOICE_DASH``
+------------------------------------
+
+.. versionadded:: 6.1
+.. deprecated:: 6.1
+
+Default: ``False``
+
+Set this transitional setting to ``True`` to revert back to the old default
+blank choice label in forms.
+
 .. setting:: USE_I18N
 
 ``USE_I18N``
@@ -3851,6 +3864,7 @@ File uploads
 Forms
 -----
 * :setting:`FORM_RENDERER`
+* :setting:`USE_BLANK_CHOICE_DASH`
 
 Globalization (``i18n``/``l10n``)
 ---------------------------------
diff --git a/docs/releases/6.1.txt b/docs/releases/6.1.txt
index 142ddb631e..a4e10d2102 100644
--- a/docs/releases/6.1.txt
+++ b/docs/releases/6.1.txt
@@ -244,7 +244,11 @@ File Uploads
 Forms
 ~~~~~
 
-* ...
+* The new constant ``django.db.models.fields.BLANK_CHOICE_LABEL`` defines a
+  more accessible and translatable default label for the blank choice in
+  forms, which is appended to most ``choices`` lists. The transitional setting
+  :setting:`USE_BLANK_CHOICE_DASH` allows you to revert back to the old
+  default label.
 
 Generic Views
 ~~~~~~~~~~~~~
@@ -540,6 +544,11 @@ Miscellaneous
   used as the top-level value. :lookup:`Key and index lookups <jsonfield.key>`
   are unaffected by this deprecation.
 
+* The ``django.db.models.fields.BLANK_CHOICE_DASH`` constant is deprecated
+  in favor of the new constant ``django.db.models.fields.BLANK_CHOICE_LABEL``.
+
+* The :setting:`USE_BLANK_CHOICE_DASH` transitional setting is deprecated.
+
 * The undocumented ``get_placeholder`` method of
   :class:`~django.db.models.Field` is deprecated in favor of the newly
   introduced ``get_placeholder_sql`` method, which has the same input signature
-- 
cgit v1.3