[Topic] Adds form documentation about input/label by rianrietveld · Pull Request #202 · wpaccessibility/wp-a11y-docs

rianrietveld · 2025-10-11T07:02:00Z

Related issues: #155, #200
Preview: https://wpaccessibility.org/pr-preview/pr-202/docs/topics/forms/input-label/

The page input-label is now a section with 5 subpages

Input field and form label (intro).
Give a form field an accessible name with a label.
Placeholders in form fields.
Only include text in the label.
Place the label above the form field (best practice)

I also created an additial page "Accessible name" in the frontend code section to refer to.
Preview: https://wpaccessibility.org/pr-preview/pr-202/docs/topics/code/accessible-name/

github-actions · 2025-10-11T07:02:55Z

PR Preview
Preview removed because the pull request was closed.
2025-10-23 05:53 UTC

…15-label-input

…s into 115-label-input" This reverts commit 8e2f05f, reversing changes made to 33ecaa5.

Co-authored-by: Gary Jones <[email protected]>

@GaryJones

props @GaryJones

Co-authored-by: Gary Jones <[email protected]>

rianrietveld · 2025-10-13T06:46:59Z

@GaryJones Thanks for the review, I committed your suggestions. I hope I got them all.

A new feature I discovered while doing so is that GitHub offers the option to bundle the suggested commits. That's really nice, because then GH Actions doesn't create a new build with every single commit.

Thanks Rosanne van Staalduinen

AnneliesDT

In general: am I missing information about instructions in labels? Do we need to explain how to solve the issue with postcodes, phone numbers, mail addresses etc? Or is that a different topic altogether? Because in the related WCAG criteria there's mention of 3.3.2, but I read a lot about labels, but nothing on instructions.

AnneliesDT · 2025-10-15T09:22:18Z

+
+## Related pages in this documentation
+
+- [Accessible name]({{site.baseurl}}/docs/topics/code/accessible-name/).


I am on the page Accessible Name, and i get related page: Accessible Name. I think it would be logical to add the other pages underneath Input and label here, because now I would want to read on about Placeholders (next page in the tree).

@AnneliesDT
About "am I missing information about instructions in labels"?
I'm following (sort of) the docs as I write for the NLDS
When the basics is published I want to add extra pages like: When which form element". In Dutch: https://nldesignsystem.nl/richtlijnen/formulieren/wanneer-welk-form-element/iedereen-kan-invullen/
When that is written I will link to that new content.
My plan is to translate all pages below Forms (Formulieren) and adjust the for WordPress needs.
Only when the content is there I can cross link and refer.
Step by step, first the basics and then the extra's.

@AnneliesDT About "pages underneath Input and label here".
I was thinking the same, I want to investigate if that functionality already was there in the software, I will create an issue for that.

AnneliesDT · 2025-10-15T09:24:42Z

+
+# Placeholders in form fields
+
+For all users to understand how to fill out a form, the **labels** should be connected to form control.


For less technical people, what does form control mean? This is quite a vague sentence. We were about to read about placeholders, and now you're talking about labels again. So what is the relation here?

@AnneliesDT I decided labels and placeholders belong to each other because placeholders are often misused as a label.
About the form control, some form elements are checkboxes or radio buttons and not really fields.
As a word that catches them all. If you know a better word, please let me know.

AnneliesDT · 2025-10-15T09:26:23Z

+
+For all users to understand how to fill out a form, the **labels** should be connected to form control.
+
+The **placeholder** represents a short hint (a word or short phrase) intended to aid the user on _what_ to fill out a form field. A hint could be a sample value or a brief description of the expected format.


Can we add a visual here? This sentence is quite difficult to read if you don't know already what it is. Or say: "A placeholder usually is a brief description of what needs to be in the form field, put into the field itself. It disappears when the user starts typing in the form field."

I changed the text and added the disappearing value with the disadvantages.

AnneliesDT · 2025-10-15T09:27:49Z

+
+Only using a placeholder (without a connected label) has some disadvantages:
+- the form field doesn't have a proper accessible name.
+- the placeholder text may become unreadable when a user zooms in and the text becomes too large for the input field.


Not only that: it disappears when the user starts typing, and when it contained important information about the format, the user cannot take another look at it. Especially important for people with memory/focus issues. It's why you need to put important input information in the label or in a description right above the form field.

AnneliesDT · 2025-10-15T09:29:16Z

+- the form field doesn't have a proper accessible name.
+- the placeholder text may become unreadable when a user zooms in and the text becomes too large for the input field.
+
+For a longer hint or other advisory text, place the text next to the form field. In this case, use [aria-describedby]({{site.baseurl}}/docs/topics/forms/descriptions/) to connect the descriptive text to the field.


Not next to, close to, preferable above. "next to" is also a WCAG violation if you're not on desktop and this is the only hint of location)

I changed 'next' into close, as the 'order' will be addressed with in description section.

AnneliesDT · 2025-10-15T09:32:38Z

+
+Additional HTML elements can cause problems when screen readers announce the label or when a user tries to focus the input field by voice recognition.
+
+- The text inside the addition interactive elements will be added to the [accessible name]({{site.baseurl}}/docs/topics/code/accessible-name/). If that text is, for example, a tooltip, the accessible name of the form input can become unreadable, incomprehensible, or just plain wrong.


i think this should be "additional"

AnneliesDT · 2025-10-15T09:33:19Z

+- If there is a clickable item inside the label, clicking it can result in also selecting the form control if it's a checkbox.
+- The reading order (meaningful sequence) of the content can get illogical.
+
+Keep the label with a form control to the point.  Include additional information above the form, either as links above the label or form field (whichever makes sense in terms of reading order) or as a description next to the field.


extra space after the dot before Include

AnneliesDT · 2025-10-15T09:35:40Z

+
+Keep the label with a form control to the point.  Include additional information above the form, either as links above the label or form field (whichever makes sense in terms of reading order) or as a description next to the field.
+
+There is an exception when using an implicitly associated form control. But adding an input field inside a label has accessibility concerns. Read [MDN about label accessibility](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/label#accessibility).


My noob brain is confused here again. What does this mean? What is an implicitly associated form control? Next sentence also misses context. In my opinion, skip this, or explain a bit more about exceptions and expand a little. We were explaining how to do it, not confuse them with a vague exception.

This is important, because Contact Forms 7 uses implicitly associated form controls as default.
I will add an example.

AnneliesDT · 2025-10-15T09:36:13Z

+
+## Related pages in this documentation
+
+- [Accessible name]({{site.baseurl}}/docs/topics/code/accessible-name/).


Add more pages here.

Which ones would you like to add here?
Note: I only can add pages that are already published. More links to come when more info is published.

AnneliesDT · 2025-10-15T09:37:14Z

+## Be consistent
+
+As this is best practice you are not required to place the label above the form field. But whatever you decide, be consistent. That way the users understand better and faster how to fill out the form.
+


Related pages are missing here.

See previous comments

add form documentation about input/label

33ecaa5

rianrietveld added this to WP A11y docs Oct 11, 2025

rianrietveld moved this to PRs to review in WP A11y docs Oct 11, 2025

rianrietveld linked an issue Oct 11, 2025 that may be closed by this pull request

[Topic] Input fields and form labels #155

Closed

rianrietveld requested review from a team, AnneliesDT, GaryJones, aialvi and joedolson and removed request for a team and aialvi October 11, 2025 07:14

rianrietveld self-assigned this Oct 11, 2025

rianrietveld removed a link to an issue Oct 11, 2025

[Topic] Input fields and form labels #155

Closed

rianrietveld linked an issue Oct 11, 2025 that may be closed by this pull request

[Topic] Accessible name #200

Closed

rianrietveld added 2 commits October 11, 2025 09:29

Merge branch 'main' of github.com:wpaccessibility/wp-a11y-docs into 1…

8e2f05f

…15-label-input

Revert "Merge branch 'main' of github.com:wpaccessibility/wp-a11y-doc…

51b61b9

…s into 115-label-input" This reverts commit 8e2f05f, reversing changes made to 33ecaa5.

GaryJones requested changes Oct 11, 2025

View reviewed changes

rianrietveld and others added 10 commits October 13, 2025 08:22

changes after text review

3569ce7

Co-authored-by: Gary Jones <[email protected]>

changes after text review

b112c81

Co-authored-by: Gary Jones <[email protected]>

changes after text review

6732e41

Co-authored-by: Gary Jones <[email protected]>

changes after text review

10d9783

Co-authored-by: Gary Jones <[email protected]>

changes after text review

4fab98f

Co-authored-by: Gary Jones <[email protected]>

changes after text review

e8db7e2

Co-authored-by: Gary Jones <[email protected]>

changes after text review

4227e16

Co-authored-by: Gary Jones <[email protected]>

changes after text review

e56f9cb

Co-authored-by: Gary Jones <[email protected]>

changes after text review

0cf7d31

Co-authored-by: Gary Jones <[email protected]>

fix order elements in example

8e6ab55

props @GaryJones

rianrietveld requested a review from GaryJones October 13, 2025 06:36

Apply suggestions from code review

1901442

Co-authored-by: Gary Jones <[email protected]>

rianrietveld linked an issue Oct 13, 2025 that may be closed by this pull request

[Topic] Input fields and form labels #155

Closed

GaryJones previously approved these changes Oct 14, 2025

View reviewed changes

aialvi previously approved these changes Oct 14, 2025

View reviewed changes

rianrietveld added 2 commits October 15, 2025 08:36

Apply suggestions from text review

214cfaf

Thanks Rosanne van Staalduinen

Linter

45276b2

rianrietveld dismissed stale reviews from aialvi and GaryJones via 45276b2 October 15, 2025 06:37

typo

54f1264

rianrietveld requested a review from GaryJones October 15, 2025 06:46

AnneliesDT requested changes Oct 15, 2025

View reviewed changes

rianrietveld linked an issue Oct 16, 2025 that may be closed by this pull request

[Topic] Placeholders #163

Closed

Apply suggestions from text review

2407523

rianrietveld requested review from AnneliesDT and removed request for AnneliesDT, GaryJones and joedolson October 20, 2025 10:27

rianrietveld merged commit be7a368 into main Oct 23, 2025
1 check passed

rianrietveld deleted the 115-label-input branch October 23, 2025 05:53

github-project-automation Bot moved this from PRs to review to Done in WP A11y docs Oct 23, 2025

rianrietveld mentioned this pull request Oct 25, 2025

Restore logo #209

Merged


		## Related pages in this documentation

		- [Accessible name]({{site.baseurl}}/docs/topics/code/accessible-name/).


		# Placeholders in form fields

		For all users to understand how to fill out a form, the labels should be connected to form control.


		For all users to understand how to fill out a form, the labels should be connected to form control.

		The placeholder represents a short hint (a word or short phrase) intended to aid the user on _what_ to fill out a form field. A hint could be a sample value or a brief description of the expected format.


		Additional HTML elements can cause problems when screen readers announce the label or when a user tries to focus the input field by voice recognition.

		- The text inside the addition interactive elements will be added to the [accessible name]({{site.baseurl}}/docs/topics/code/accessible-name/). If that text is, for example, a tooltip, the accessible name of the form input can become unreadable, incomprehensible, or just plain wrong.


		Keep the label with a form control to the point. Include additional information above the form, either as links above the label or form field (whichever makes sense in terms of reading order) or as a description next to the field.

		There is an exception when using an implicitly associated form control. But adding an input field inside a label has accessibility concerns. Read [MDN about label accessibility](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/label#accessibility).

		## Be consistent

		As this is best practice you are not required to place the label above the form field. But whatever you decide, be consistent. That way the users understand better and faster how to fill out the form.

Conversation

rianrietveld commented Oct 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Oct 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rianrietveld commented Oct 13, 2025

Uh oh!

AnneliesDT left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rianrietveld Oct 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rianrietveld Oct 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

rianrietveld commented Oct 11, 2025 •

edited

Loading

github-actions Bot commented Oct 11, 2025 •

edited

Loading

rianrietveld Oct 16, 2025 •

edited

Loading

rianrietveld Oct 16, 2025 •

edited

Loading