Form Field label - improve documentation to explain how to omit labels

[Alastair Porter]

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.

[Amar]

​https://github.com/django/django/pull/20654

[Shubh Rai]

Replying to Amar:

​https://github.com/django/django/pull/20654

Hi, I noticed the PR is failing some checks . Are you still working on this? If not, I would be happy to help work on the fix.

[Amar]

Hey Shubh, yeah I'm still working on this.

If you look at what's failing, the two checks are MySQL/MySQL GIS database tests — this is a docs-only change, so those have nothing to do with my PR.

Also worth noting the PR hasn't gotten any reviews yet, so there's not much to act on from my side right now.

Btw if you haven't seen it, Sarah Boyce has a talk on the Djangonaut Space channel (​Your First Django Contribution , around the 8:55 mark) where she talks about giving contributors some time to work through their PRs before stepping in. Really good watch.

Thanks for the interest though!

[Jacob Walls <jacobtylerwalls@…>]

In 8401071:

Fixed #36904 -- Clarified how to hide form field labels in docs.

[Jacob Walls <jacobtylerwalls@…>]

In abf1df0:

[6.0.x] Fixed #36904 -- Clarified how to hide form field labels in docs.

Backport of 8401071c52d19a2bdd987a2dbe79c440f01dfae9 from main.