Skip to main content

Creating accessible HTML forms for websites and applications

This guide describes in detail the coding best-practices that are implemented in the Accessible Form Validation CodePen example used for the “Live Training: Accessible HTML Forms”.

The following content summarizes the accessibility best-practices that are demonstrated in the following training course: “Live Training: Accessible HTML Forms”.

Are you a designer, developer or tester that works with custom built web-based HTML forms?

The accessible form training features a sample form using HTML, CSS, and Vanilla JavaScript coding best-practices that meet all Web Content Accessibility Guidelines (WCAG) 2.1 Level A and Level AA requirements as well as inline form validation. This guide is used as a supplement to the “Live Training: Accessible HTML Forms” covering in detail accessible design best practices, development using HTML, CSS, and Vanilla JavaScript, keyboard-only, browser zoom 400%, mobile device emulator, text resize 200%, Windows high contrast theme, and NVDA screen reader testing.

The following tips and techniques have been implemented in the Accessible Form Validation CodePen example (external link).

Skip table of contents

Table of Contents

You skipped the table of contents section.

Designing and developing accessible forms

When designing your forms make sure you design for at least mobile and desktop screen sizes. This will help developers understand how elements should rearrange when using smaller screens or browser zoom 400%. For optimum readability use 16px font size as your smallest font and 1.5 percent line height.

  • Use at least one heading at the top of your form that is descriptive and summarizes the purpose of the form.
  • Use descriptive label text.
  • Use helper text to clarify formatting requirements.
  • Use native HTML form elements (external link).
  • Avoid custom date pickers they are usually not accessible, instead use the input type="date" HTML native element (external link).
  • Don’t use placeholder (external link) text in input fields.
  • Use the autocomplete input attribute (external link) for common input, select, and textarea fields.
  • Use inline error messages that show below the field. Make sure they are descriptive and helpful and advise the user how to fix the issue. Error messages should include the field label text (don’t use: “This field can’t be empty” instead use “The first name field can’t be empty”).
  • Make sure all text colors including the color of an HTML input element's value meet the 4.5:1 contrast (external link) requirement
  • Make sure your form elements borders (input, select, textarea, checkbox, radio button) and selected state colors all meet the 3:1 non-text contrast (external link). Don’t hide input field borders or make the border color too light.
  • Make sure the focus outline is visible on all focusable form elements. Tab through the form and verify that it meets the 3:1 non-text contrast (external link) requirement.
  • Don’t rely on using color alone to convey meaning (external link). Include an error icon with your error message.
  • Use browser native default CSS styles for radio buttons, checkboxes, or select element chevron symbols to prevent 3:1 contrast requirement failure when using operating system, browser, or plugin contrast theme overwrites.

Developer guide to be used with the Accessible Form CodePen example

The following tips and techniques have been implemented in the embedded CodePen.

To view the Pen Accessible form validation (external link) by EOTSS ACCESS @EOTSS-ACCESS (external link) on CodePen (external link).

Form instructions

Form instructions must always be listed at the start of the form. When designing a side-by-side (left and right) layout for desktop make sure you put the instructions on the left side not the right side. Because content typically gets stacked when viewed on mobile or when using browser zoom. In that scenario the left content will be stacked above the right content.

Required field sentence

If your form has required fields then always include the following instruction sentence above the first form element:
“Fields marked with a red asterisk * are required.”

If you are using a red asterisk in your field labels, then the asterisk in your instruction sentence should also be red.

screenshot of required field sentence

Form Instructions for multi-page forms

When using multi-page form layout only list form instructions relevant to that page or view. For the first screen of a multi-page form also includes documents or information that may be required for the user to gather before filling out the form. 
Always list the required field instructions on top of each screen 

Multi-page forms

Don’t rely on progress indicators alone, instead, use the heading technique approach to indicate which step the user is on. The h1 heading will remain the same on each page or screen of your multi-page form. Use a h2 heading to define each step of the form. 

Example for multi-page form headings

Heading 1: Mass Health Application
Heading 2: Mailing Address (Step 2 of 4)

Multi-page form required field instructions

If your multi-page form has required fields then always include the following instruction sentence above the first form element on each page or screen that contains required form fields:
“Fields marked with a red asterisk * are required.”

Multi-lingual forms

Make sure you test your form design using a language with longer text labels using Google translate (i.e., English to German). 

Grouping multiple fields

Use the fieldset and legend tag to group multiple fields. You can style the legend tag to look like a heading. Designers can use existing heading styles in their design to define a heading when grouping multiple fields. However, developers will use the fieldset tag to wrap the grouped fields and the legend tag instead of a heading tag to wrap the heading text. Using legend tags instead of heading tags provides additional clarity for screen reader users when tabbing through a form. The example form shows several groupings using this technique.

Visible input field labels

Use visible input field labels that are descriptive. Each field must have its own visible label. Allow for extra space in your design for form translations. 

Dropdown select elements

Check the longest option for your dropdown select elements to ensure that they are not clipped when selected. Avoid hard-coded width or height values. Use min-width and padding instead. 

screenshot of select state dropdown
Clipped text in the state dropdown caused by a hard-coded width on the select tag

For selecting multiple options when using a select dropdown, add the HTML “multiple” Attribute to the select tag.

Helper text used for formatting instructions

Putting form field specific helper text used for formatting instructions as part of the label tag prevents misalignments of form fields when form fields are laid out side by side.

For longer formatting instructions that don’t fit within the designated space for the form field place them above the form element’s label reference the instructions using aria-describedby.

We recommend using flexbox alignment (external link) CSS for all form elements, this allows for better reflow and repaint when the page loads and also simplifies media query CSS used to stack form elements for mobile devices and browser zoom.

Helper Text Alignment Example 1: 

screenshot of helper text as part of the label
Helper text as part of the label: this is the preferred method for desktop layout where all fields align properly on the horizontal main axis.

Helper Text Alignment Example 2:

screenshot of helper text where all content aligns with the bottom of the outer div container and the field labels don’t align on the same horizontal main axis
Helper text on its own line and using Flex layout using “align-items: flex-end” CSS: this is where all content aligns with the bottom of the outer div container and the field labels don’t align on the same horizontal main axis. 

Helper Text Alignment Example 3:

screenshot of helper text where all content aligns with the top of the outer div container
Helper text on its own line and using Flex layout using “align-items: flex-start” CSS: this is where all content aligns with the top of the outer div container and the form fields don’t align on the same horizontal main axis.

Error Messages

Visual Identifiers for Error Messages

Using a red error icon in addition to red text for error messages is considered best practice.  Don’t rely on color alone to indicate error messages. Users who are color blind may not be able to identify the error message based on color alone, also, when using a high a contrast theme (i.e., Night Sky theme in Windows) the error text and icon will be white.

Screenshot of error message showing red text with error icon
Error message showing red text with error icon
Screenshot of error message showing white text with error icon – Windows Night Sky theme
Error message showing white text with error icon – Windows Night Sky theme

Showing error messages on form submit

For your form validation to deliver the best user experience, validate your form on submit. Form submit should be triggered by activating the "submit" button.

Important: avoid showing error messages using the JavaScript "blur" event which occurs when a field loses keyboard focus or after the user tabs off the form field. This is important especially for larger forms containing more than one field. Using on "blur" validation can be very disorienting and confusing for screen reader users since the error message is announced after the user tabs off the field. Some screen reader users have partial vision and rely on assistive technology to supplement their ability to see. The visual and assistive technology experiences should always match and be consistent.

Removing errors after they have been fixed using the JavaScript "blur" event

After the user fixes the error on an input field and the field loses focus by either clicking elsewhere on the screen or tabbing off the field, the error message should be removed. Also, any ARIA attributes used to indicate that the field has an error should be either removed or set to “false” (i.e., aria-invalid="false").

Testing your form

As a developer or tester, you can perform the following checks to ensure your form is accessible.

Testing responsive layout

Test your form using browser zoom up to 400% to guarantee proper “reflow” of all content and use the browser’s developer tool to emulate mobile devices and tablets to ensure your content layout works for all test cases (desktop, tablet, mobile, browser zoom up to 400%).

Resize text and text spacing

Allow for ample space in your design to accommodate users to resize text (external link) to 200% and for custom text spacing (external link) using the text spacing bookmarklet (external link).

Testing only using the keyboard

Tab through the form and make sure every element has a visible focus indicator (should be a rectangular shape around the element) that meets the 3:1 contrast requirement. Make sure you can choose an option when activating a select dropdown using the arrow keys. Test your radio buttons (use arrow keys to select a radio button) and checkboxes (use spacebar to select a checkbox).
Important: when activating the submit button and inline errors are shown the focus indicator needs to get moved to the first field with an error.

screenshot of an input field showing a blue focus outline
Blue focus outline on an input field
screenshot of a checkbox with a blue focus outline
Blue focus outline on a checkbox
screenshot of a radio button with a blue focus outline
Blue focus outline on a radio button

Testing using the Google developer tool

Use the Google developer tool to inspect your rendered code to verify ARIA references and state changes (i.e., aria-required, aria-invalid, aria-describedby, etc.).  You can also inspect CSS and verify color contrast for text, borders, and focus outlines using the WebAIM contrast checker (external link).

Testing using the ANDI tool

Using the ANDI tool (external link), you can test how a screen reader may announce your labels, helper text, and error messages.

Testing using a screen reader

Only test using a screen reader (NVDA, JAWS, or VoiceOver) if you have been formally trained. 

Additional Resources

For help including design reviews, code reviews, or additional training contact the ACCESS team using the ACCESS team’s intake form.

Help Us Improve Mass.gov  with your feedback

Please do not include personal or contact information.
Feedback