Components

Form templates

Patterns for some of the most commonly used forms

General accessibility guidance for forms

  • Customize accessibly. As you customize these templates, make sure they meet the accessibility guidelines in this introduction and as described for each control.
  • Don’t control element order with CSS. Display form controls in the same order in HTML as they appear on screen. Don’t use CSS to rearrange the form controls. Screen readers narrate forms 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 screen reader users to navigate the form.
  • Use legends. Use a single legend for fieldset (this is required). One example of a common use of fieldset and legend 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.
Note: These components have been designed to support a wide range of screen readers, but they may not work with all versions.

Known issues with screen readers

  • VoiceOver on iOS currently does not support fieldset and legend for forms. You can address this 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 currently does not support aria-describedby. Use aria-labelledby instead, and include all related fields, including, labels, legend, and hint text

Name form

Collect a full name as separate elements of data

Name
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
<form class="usa-form">
  <fieldset class="usa-fieldset">
    <legend class="usa-legend">Name</legend>
    <label class="usa-label" for="title">Title <span class="usa-hint">(optional)</span></label>
    <input class="usa-input usa-input--small" id="title" name="title" type="text">

    <label class="usa-label" for="first-name">First name</label>
    <input class="usa-input" id="first-name" name="first-name" type="text" required aria-required="true">

    <label class="usa-label" for="middle-name">Middle name <span class="usa-hint">(optional)</span></label>
    <input class="usa-input" id="middle-name" name="middle-name" type="text">

    <label class="usa-label" for="last-name">Last name</label>
    <input class="usa-input" id="last-name" name="last-name" type="text" required aria-required="true">
  </fieldset>
</form>

When to use a name form

  • You need separate data elements. When you need to collect users’ full names and store the parts separately in a database.

When to consider something else

  • You don’t need separate data elements. If you don’t need to parse out the separate pieces of a person’s name, consider letting them enter it into a single text field.

Usability guidance

  • Avoid dropdowns. Leave the title and suffix fields as text boxes instead of offering dropdowns. There are many possible titles and suffixes; text boxes accommodate them all.
  • Don’t restrict characters. Do not restrict the types of characters users can enter in any of these fields. Names can include characters outside the standard Roman alphabet.

Accessibility

Package information

  • Package usage: @import form-templates
  • Requires: required, global

Address form

Enter a standard U.S. mailing or shipping address

Mailing address
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
<form class="usa-form usa-form--large">
  <fieldset class="usa-fieldset">
    <legend class="usa-legend">Mailing address</legend>
    <label class="usa-label" for="mailing-address-1">Street address 1</label>
    <input class="usa-input" id="mailing-address-1" name="mailing-address-1" type="text">

    <label class="usa-label" for="mailing-address-2">Street address 2 <span class="usa-hint">(optional)</span></label>
    <input class="usa-input" id="mailing-address-2" name="mailing-address-2" type="text">

    <div class="grid-row grid-gap">
      <div class="mobile-lg:grid-col-8">
        <label class="usa-label" for="city">City</label>
        <input class="usa-input" id="city" name="city" type="text">
      </div>
      <div class="mobile-lg:grid-col-4">
        <label class="usa-label" for="state">State</label>
        <select class="usa-select" id="state" name="state">
          <option value>- Select -</option>
          <option value="AL">Alabama</option>
          <option value="AK">Alaska</option>
          <option value="AZ">Arizona</option>
          <option value="AR">Arkansas</option>
          <option value="CA">California</option>
          <option value="CO">Colorado</option>
          <option value="CT">Connecticut</option>
          <option value="DE">Delaware</option>
          <option value="DC">District of Columbia</option>
          <option value="FL">Florida</option>
          <option value="GA">Georgia</option>
          <option value="HI">Hawaii</option>
          <option value="ID">Idaho</option>
          <option value="IL">Illinois</option>
          <option value="IN">Indiana</option>
          <option value="IA">Iowa</option>
          <option value="KS">Kansas</option>
          <option value="KY">Kentucky</option>
          <option value="LA">Louisiana</option>
          <option value="ME">Maine</option>
          <option value="MD">Maryland</option>
          <option value="MA">Massachusetts</option>
          <option value="MI">Michigan</option>
          <option value="MN">Minnesota</option>
          <option value="MS">Mississippi</option>
          <option value="MO">Missouri</option>
          <option value="MT">Montana</option>
          <option value="NE">Nebraska</option>
          <option value="NV">Nevada</option>
          <option value="NH">New Hampshire</option>
          <option value="NJ">New Jersey</option>
          <option value="NM">New Mexico</option>
          <option value="NY">New York</option>
          <option value="NC">North Carolina</option>
          <option value="ND">North Dakota</option>
          <option value="OH">Ohio</option>
          <option value="OK">Oklahoma</option>
          <option value="OR">Oregon</option>
          <option value="PA">Pennsylvania</option>
          <option value="RI">Rhode Island</option>
          <option value="SC">South Carolina</option>
          <option value="SD">South Dakota</option>
          <option value="TN">Tennessee</option>
          <option value="TX">Texas</option>
          <option value="UT">Utah</option>
          <option value="VT">Vermont</option>
          <option value="VA">Virginia</option>
          <option value="WA">Washington</option>
          <option value="WV">West Virginia</option>
          <option value="WI">Wisconsin</option>
          <option value="WY">Wyoming</option>
          <option value="AA">AA - Armed Forces Americas</option>
          <option value="AE">AE - Armed Forces Africa</option>
          <option value="AE">AE - Armed Forces Canada</option>
          <option value="AE">AE - Armed Forces Europe</option>
          <option value="AE">AE - Armed Forces Middle East</option>
          <option value="AP">AP - Armed Forces Pacific</option>
        </select>
      </div>
    </div>

    <label class="usa-label" for="zip">ZIP</label>
    <input class="usa-input usa-input--medium" id="zip" name="zip" type="text" pattern="[\d]{5}(-[\d]{4})?">
  </fieldset>
</form>

When to use an address form

  • You need separate data elements. When you need to be able to parse out the specific parts of a mailing address.

When to consider something else

  • Nonstandard addresses. If you need to collect addresses that may not fit this format (for example, international addresses).
  • You don’t need separate data elements. If you don’t need to be able to parse out the individual pieces of an address, consider letting users type the entire address into one large text area.

Usability guidance

  • Don’t call out required fields. Call out optional fields instead. Users can infer that non-optional fields are required.
  • Avoid dropdowns. If possible, let users type their state’s abbreviation when they reach the state drop-down menu.
  • Support both five- and nine-digit ZIP codes. Some addresses require a nine-digit ZIP code. If you would like to use an input mask, it should be “#####-####” so that the text is properly formatted, regardless of whether a user enters a five- or nine-digit ZIP code.

Accessibility

Package information

  • Package usage: @import form-templates
  • Requires: required, global

Sign-in form

Sign a user in to a website or application

Sign in or create an account

Show password

Forgot username?

Forgot password?

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
<form class="usa-form">
  <fieldset class="usa-fieldset">
    <legend class="usa-legend">Sign in</legend>
    <span>or <a href="javascript:void(0);">create an account</a></span>

    <label class="usa-label" for="username">Username or email address</label>
    <input class="usa-input" id="username" name="username" type="text" autocapitalize="off" autocorrect="off">

    <label class="usa-label" for="password-sign-in">Password</label>
    <input class="usa-input" id="password-sign-in" name="password" type="password">
    <p class="usa-form__note">
      <a title="Show password" href="javascript:void(0);"
        class="usa-show-password"
        aria-controls="password-sign-in">Show password</a>
    </p>

    <input class="usa-button" type="submit" value="Sign in">
    <p><a href="javascript:void(0);" title="Forgot username">
      Forgot username?</a></p>
    <p><a href="javascript:void(0);" title="Forgot password">
      Forgot password?</a></p>
  </fieldset>
</form>

When to use a sign-in form

  • Accessing customized or private content. When users expect information to be customized or private, place it behind a sign-in form.

When to consider something else

  • Accessing public content. Allow users to access as much as of your online services as possible without having to sign in. Sign-in forms are a barrier between users and the content they want.

Usability guidance

  • Less is more. Make your explanations concise. Users sign in faster when less text surrounds the form.
  • Allow email addresses to sign in. People have an easier time remembering their email address than they do a unique username.
  • Consider keeping users signed in. If you must include a sign-in form, consider allowing users to stay logged in (“Remember me”) on trusted computers so they can avoid this barrier in the future.
  • Make it easy to retrieve forgotten sign-in info. Most authentication failures occur because a user has forgotten their username or password. This is especially common when a long time passes between visits, as is the case with most federal websites.
  • Toggle password masking. Password masking (replacing what the user types with a generic symbol) makes it more likely that users will make mistakes when trying to sign in, and doesn't offer much in the way of additional security. Allow users to unmask the password field so they can see what they type. This is especially useful on mobile devices, when users are more likely to mistype.

Accessibility

  • Customize accessibly. As you customize this form template, make sure it continues to follow the accessibility guidelines for form templates and the accessibility guidelines for form controls.
  • Give adequate advance notice before automatic sign-out. Don’t automatically sign out a user without giving them 20 seconds' advance notice to request more time. Users with disabilities sometimes require more time to respond to prompts.

Package information

  • Package usage: @import form-templates
  • Requires: required, global

Password reset form

Reset a password

Reset password Please enter your new password

Password information

Length requirements
Character constraints, if any

Show my typing

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
<form class="usa-form">
  <fieldset class="usa-fieldset">
    <legend class="usa-legend">Reset password</legend>
    <span>Please enter your new password</span>

    <div class="usa-alert usa-alert--info usa-alert--validation">
      <div class="usa-alert__body">
        <h3 class="usa-alert__heading">Password information</h3>
        <p class="usa-alert__text">
          Length requirements
          <br>
          Character constraints, if any
        </p>
      </div>
    </div>

    <label class="usa-label" for="password-reset">New password</label>
    <input class="usa-input" id="password-reset" name="password" type="password">

    <label class="usa-label" for="confirmPassword">Confirm password</label>
    <input class="usa-input" id="confirmPassword" name="confirmPassword" type="password">
    <p class="usa-form__note">
      <a href="javascript:void(0);"
        class="usa-show-multipassword"
        aria-controls="password-reset confirmPassword">Show my typing</a>
    </p>

    <input class="usa-button" type="submit" value="Reset password">
  </fieldset>
</form>

When to use a password reset form

  • Any time your site requires passwords for sign-in. To offer a way to easily reset a password any time users are able to sign in to your site.

Usability guidance

  • Users forget passwords. If users need a password to access your site, they will forget that password and need a way to reset it.
  • Be clear about password requirements. State any password requirements (for example, “Must include one capital letter”) up front. Don’t leave users guessing about password requirements, only to hit them with an error message later.
  • More about passwords: For more guidance on password requirements, see NIST's Appendix A—Strength of Memorized Secrets.

Accessibility

Implementation

Package information

  • Package usage: @import form-templates
  • Requires: required, global