Templates

Form templates

Patterns for some of the most commonly used forms

Accessibility guidance

  • Don’t control element order with CSS. Display form controls in the same order in the HTML as they appear on screen. Don’t use CSS to rearrange the form controls. Screen readers narrate form elements in the order they appear in the HTML.
  • Align validation with inputs. Visually align validation messages with the input fields so people using screen magnifiers can read them quickly.
  • Use proper markup. Group each set of thematically related controls in a fieldset element. Use the legend element to offer a label within each one. The fieldset and legend elements make it easier for those who use screen readers to navigate the form.
  • Use legends. Use a single legend for fieldset (this is required). One common use of the fieldset and legend elements is a question with radio-button options for answers. The question text and radio buttons are wrapped in a fieldset, with the question itself being inside the legend tag.
  • Embed multiple fieldsets and legends for more complex forms.
  • Use simple vertical layouts. Keep your form blocks in a vertical pattern. This approach is ideal, from an accessibility standpoint, because of limited vision that makes it hard to scan from right to left.

Disabled states for components in forms

  • Avoid disabled states, especially for text inputs. Disabled states have low color contrast, do not offer meaningful feedback to screen reader users, and keyboard navigators can’t focus on them. These states can also be generally confusing to users. Instead, keep form elements enabled. Offer contextual helper text, tooltips, helpful error messages and inline validation to help people correct mistakes and move through the form.

  • If you must use disabled states, follow best practices. Some disabled states can prevent errors by telling users that a system is loading or processing (for example, to prevent multiple form submissions). In specific cases, such as an unavailable date in appointment scheduling, a disabled state may be helpful to show users that an option exists but is currently unavailable.

    When using disabled states, be very clear:
    • Explain why an element is disabled, using helper text or tooltips
    • Use inline validation to minimize errors in real time
    • Support screen reader users and keyboard navigators by using aria-disabled=true instead of the disabled attribute to indicate the presence of a disabled element
    • Use JavaScript to programmatically disable the element to prevent clicks

    For more detail, you can read USWDS’s 2023 literature review on disabled states.

Identifying required fields

  • Show whether a field is required or optional. Mark required fields as required by using a red asterisk (*).
  • Use text descriptions. Combine red asterisks (*) with a text description at the top of the form instructing the user of its meaning.
    Example: “A red asterisk (*) indicates a required field.”
  • Use the required attribute. Add the required attribute to your form elements to indicate that a field must be filled out before submitting the form.
  • Mark optional fields as "optional." Label optional fields with the word “optional” placed in parentheses.
    Example: (optional)
  • Let users know if there is an error. Use a message or alert to notify the user if a field that is required was not completed, and indicate which field was not completed. Additionally, include an error notification in the page title (title element) for screen readers.
  • Note: One-field forms are the exception and do not need to be marked with a required label or symbol.

Known issues with screen readers

  • VoiceOver on iOS currently does not support fieldset and legend elements for forms. You can address this issue by using aria-labelledby="for-attribute-of-label id-of-legend id-of-additional-info" on each input in the fieldset. Using aria-labelledby will overwrite the default text read by the screen reader, so it is important to include all relevant information.
  • VoiceOver on OS X offers partial support for aria-describedby. There's full support for conveying description on text inputs, partial support for description changes when the text input is in focus, and no support for role="alert". Visit a11ysupport.io to view the full status of support.
Note: These components have been designed to support a wide range of screen readers, but they may not work with all versions.

Latest updates

Meaningful code and guidance updates are listed in the following table:

Date USWDS version Affects Breaking Description
2024-10-04 N/A
  • Guidance
 No

Added guidance discouraging most uses of disabled form inputs. We also added guidance on the rare instances when disabled inputs improve usability. More information: uswds-site#2776

2024-03-11 3.8.0
  • Accessibility
  • Styles
 No

Added color contrast checks for disabled tokens. On compilation, USWDS will test disabled element color contrast and provide a fallback color if minimum contrast is not met. If the fallback does not meet minimum requirements, USWDS will provide a warning in the terminal. More information: uswds#5455

2023-08-23 3.6.0
  • Accessibility
  • Styles
 No

Fixed a bug that caused some form inputs to show disabled styles when in forced colors mode. More information: uswds#5397

2023-06-09 3.5.0
  • Guidance
  • Markup
 No

Updated guidance to suggest identifying required and optional fields. We added a new section on identifying required fields and now suggest labeling required fields with a red asterisk and optional fields with the word “optional”. More information: uswds-site#1834

2023-03-13 3.4.1
  • Styles
 No

Fixed invisible link text for links styled as buttons within forms. Now link text does not match the primary button color when nested inside of a form and the usa-button class is present. More information: uswds#5112

2022-04-28 3.0.0
  • Assets
  • JavaScript
  • Styles
 Breaking

Breaking Updated to Sass module syntax and new package structure. More information: uswds#4656