Opened 3 hours ago
Last modified 2 hours ago
#36904 new Uncategorized
Form Field label - improve documentation to explain how to omit labels
| Reported by: | Alastair Porter | Owned by: | |
|---|---|---|---|
| Component: | Documentation | Version: | 6.0 |
| Severity: | Normal | Keywords: | |
| Cc: | jaffar Khan | Triage Stage: | Unreviewed |
| Has patch: | no | Needs documentation: | no |
| Needs tests: | no | Patch needs improvement: | no |
| Easy pickings: | no | UI/UX: | no |
Description
The documentation for form fields labels (https://docs.djangoproject.com/en/6.0/ref/forms/fields/#label) says
Specify label if that default behavior doesn’t result in an adequate label.
In our app we had a situation where we didn't want to use the django default label. so we set
class MyForm(forms.Form):
email1 = forms.EmailField(label=False, max_length=254)
resulting in the label being omitted from the form when we generate it due to the {% if field.label %} check at https://github.com/django/django/blob/986f7f2098a2186b4085183951cbebae15220556/django/forms/templates/django/forms/p.html#L8
When we implemented type checking with django-stubs, we got a type error here saying that label can only be str or None, prompting me to open https://github.com/typeddjango/django-stubs/issues/3028
In the resulting discussion, it became clear that it would be probably be better to use label="" to set the label to empty, but this isn't documented as a best practise.
One comment by a django-stubs maintainer (copied from the above ticket):
it just happens to work by accident. In the source code it does {% if field.label %} before rendering, so falsy values like False get skipped. But if you call label_tag() directly, it actually renders the literal text "False" as the label, and label=True crashes with a TypeError
It would be nice to update the documentation with this specific recommendation. This could be as simple as
Specify a string for label if that default behavior doesn’t result in an adequate label. Use an empty string to hide the label.