accessibility-guidelines

This document is in beta. Help us by reporting issues via Github or email

Back to the overview page

Form labels and instructions

On this page:


Summary

Provide labels to make it clear how users should fill in a form, and optionally provide extra hints to help them avoid errors.

Form elements (like a text input field or a checkbox) should have clear labels and instructions.


Requirements

Labels

Required fields

Additional instructions

Common mistakes

Why?

This ensures that everyone understands any requirements for entering data, and that screen reader users are made aware of it.

Official wording in the Web Content Accessibility Guidelines

3.3.2 Labels or Instructions: Labels or instructions are provided when content requires user input. (Level A)

See the W3C’s detailed explanation of this guideline with techniques and examples.


Guidance for Design

More guidance for design


Guidance for iOS

This section needs more content. Contribute via Github or email.


Guidance for Android

This section needs more content. Contribute via Github or email.


Guidance for Flutter

For TextField type widgets you can use the InputDecoration() class to add labels and hints to the widget.

child: TextField(
  validator: (value) {
      // validation logic
      return null;
  },
  decoration: InputDecoration(
    hintText: String, // optional hint parameter
    labelText: String, // optional label parameter
  ),
),

Guidance for Web

Associating a label with an input

<label for="uname">Username:</label>
<input type="text" id="uname" />

Failure example

<!-- Don't do this -->
<div>
  Username: 
  <input type="text" id="uname" />
</div>

Associating a hint with a text input field using aria-describedby

<label for="national-insurance-number">
  National Insurance number
</label>

<span id="national-insurance-number-hint">
  It’s on your National Insurance card, benefit letter, payslip or P60. For example, ‘QQ 12 34 56 C’.
</span>

<input id="national-insurance-number" name="national-insurance-number" type="text"
aria-describedby="national-insurance-number-hint national-insurance-number-error">

<span id="national-insurance-number-error">
  <span class="visually-hidden">Error:</span> Enter a National Insurance number in the correct format
</span>

Grouping radio buttons and checkboxes together in a fieldset with a legend

Example

Correct use of name attribute ensures checking one radio button will uncheck the other:

<fieldset>
  <legend>Would you like to receive email updates?</legend>
  <input name="rg1" type="radio" id="r1" value="yes"/>
  <label for="r1">Yes</label>
  <input name="rg1" type="radio" id="r2" value="no"/>
  <label for="r2">No</label>
</fieldset>

Failure example

Incorrect use of the name attribute prevents correct keyboard access to radio buttons:

<!-- Don't do this -->
<input name="r1" type="radio" id="r1" value="yes"/>
<label for="r1">Yes</label>
<input name="r2" type="radio" id="r2" value="no"/>
<label for="r2">No</label>

If you’re not using standard HTML checkboxes or radio button controls

Make sure that you closely follow the ‘Radio Group’ pattern in the ARIA Authoring Practices Guide, and test with one or more screen readers.

More guidance for Web


More info

Sources

Contribute

This document is in beta. Help us by reporting issues via Github or email