Jump to the navigation

Form Instructions

Status: This is an in-progress, unapproved draft.

Provide instructions to help users understand how to complete the form and individual form controls. This includes indicating any required and optional input, data formats, and other important aspects of the form.

Screen readers often switch to “Forms Mode” when they are processing content within a <form> element. In this mode they usually only read aloud form elements such as <input>, <select>, <textarea>, <legend>, and <label>. It is critical to include form instructions in ways so that they will be read aloud.

Overall instructions

Where relevant, provide overall instructions that apply to the entire form before the <form> element (to ensure that it is read aloud by screen readers before they switch to “Forms Mode”). The overall instructions should also tell the user if there are optional fields and how to skip them, if they make up a large portion of the form. Information about time limits that apply should also be mentioned, alongside with information on how to adjust, extend or turn off the limit.

In the example below, form instructions indicate how required input is highlighted, the expected format for key data fields of the particular form, and how to get additional help for each input.

Example:
  • All fields marked (required) must be completed.
  • Dates should all be typed in the format dd/mm/yyyy, (as in 21/07/2013).
  • Passwords must contain at least 8 letters and/or numbers.
  • Extra help can be found immediately after each field.

In-line instructions

In addition to the overall instructions, it is also important to provide relevant instructions within the labels of the form controls. For example, indicating required input and data formats is generally needed as part of the labels.

Providing instructions within labels

For simple use cases, providing instructions within the labels may be sufficient. While this approach tends to impact styling options, it is most reliable across different web browsers and assistive technologies.

Example:
Code snippet:
<label for="expire">Expiry date (MM/YYYY): </label> <input type="text" name="expire" id="expire">

Providing instructions outside labels

Providing instructions outside labels allows more flexible positioning and design but generally has caveats. The two approaches outlined below can be combined to achieve most impact.

Informing users

Content outside form elements may be missed by screen readers that are in “Forms Mode”. In the example below, users are informed that extra help is available for each field in the overall instructions before they enter the actual form so that they don't miss it.

Example:
  • Extra help can be found immediately after each field.
(MM/YYYY)
Code snippet:
<label for="expire">Expiry date:</label> <input type="text" name="expire" id="expire"> <span>(MM/YYYY)</span>

Note: A caveat of this approach is that users receive the instructions after the form element. This is often non-ideal, especially when the form controls are larg or when they are displayed on mobile devices and using screen magnification. In such cases these instructions may not always be easy to find.

Using WAI-ARIA

Another approach is to use the WAI-ARIA aria-describedby attribute to associate the instructions with form elements. Currently this approach may not be fully supported by all web browsers and assistive technologies.

Example:
MM/YYYY
Code snippet:
<label for="expire">Expiry date:</label>
<span>
  <input type="text" name="expire" id="expire" aria-describedby="expDesc">
  <span id="expDesc">MM/YYYY</span>
</span>

Note: A caveat of this approach is that it is mostly interpreted by screen readers, so that non-screen reader users may not get the same benefit. Until such associations are more broadly interpreted it is often useful to position the instructions directly after the form controls.

Placeholder text

Placeholder text provides instructions or an example of the required data format inside form fields that have not yet been edited by the user. Placeholder text is usually displayed with lower color contrast than text provided by users, and it disappears from form fields when users start entering text.

While placeholder text provides important guidance for many users, placeholder text is not a replacement for labels. Assistive technologies, such as screen readers, do not treat placeholder text as labels. Moreover, placeholder text is currently not broadly supported across assistive technologies.

Refer to the techniques described in Hidden labels in cases where you want to avoid redudancy of (visible) labels and placeholder text.

Example:
Code snippet:
<div>
  <label for="search">Search:</label> <input type="text" name="search" id="search" placeholder="e.g. Apple Pie">
</div>
<div>
  <label for="email">Email: </label> <input type="text" name="email" id="email" placeholder="joe@example.com">
</div>

Note: To provide more clarity, ensure that the style of placeholder text is distinguishable from regular text. This is commonly done by reducing the color contrast of placeholder text. However, ensure that also placeholder text meets at least the minimum color contrast requirement of WCAG 2.0.

Success Criteria:

  • 1.3.1 Info and Relationships: Information, structure, and relationships conveyed through presentation can be programmatically determined or are available in text. (Level A)

  • 2.4.6 Headings and Labels: Headings and labels describe topic or purpose. (Level AA)

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

  • 4.1.2 Name, Role, Value: For all user interface components (including but not limited to: form elements, links and components generated by scripts), the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to user agents, including assistive technologies. (Level A)

Techniques: