UI components

Form templates

Patterns for some of the most commonly used forms on government websites

Accessibility

As you customize these templates, make sure they meet the accessibility guidelines in this introduction and as described for each control.

Display form controls in the same order in HTML as they appear on screen. Do not use CSS to rearrange the form controls. Screen readers narrate forms in the order they appear in the HTML.
Visually align validation messages with the input fields, so people using screen magnifiers can read them quickly.
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 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.
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.

Supporting screen readers

Note: These code examples have been designed to support a range of screen readers. That said, they may not work with all versions.

Known issues

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

A standard template for collecting a person’s full name

<form class="usa-form">
  <fieldset>
    <legend>Name</legend>
    <label for="title"
      >Title <span class="usa-input-label-helper">(optional)</span></label
    >
    <input class="usa-input-tiny" id="title" name="title" type="text" />

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

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

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

Documentation

Accessibility

As you customize this form template, ensure it continues to follow the accessibility guidelines for form templates and the accessibility guidelines for form controls.

Usability

When to use

When you need to collect users’ full names and store the parts separately in a database.

When to consider something else

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.

Guidance

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

Address form

A standard template for entering a U.S. mailing or shipping address

Mailing address Street address 1 Street address 2 (optional)

City

State

ZIP

<form class="usa-form-large">
  <fieldset>
    <legend>Mailing address</legend>
    <label for="mailing-address-1">Street address 1</label>
    <input id="mailing-address-1" name="mailing-address-1" type="text" />

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

    <div>
      <div class="usa-input-grid usa-input-grid-medium">
        <label for="city">City</label>
        <input id="city" name="city" type="text" />
      </div>

      <div class="usa-input-grid usa-input-grid-small">
        <label for="state">State</label>
        <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 for="zip">ZIP</label>
    <input
      class="usa-input-medium"
      id="zip"
      name="zip"
      type="text"
      pattern="[\d]{5}(-[\d]{4})?"
    />
  </fieldset>
</form>

Documentation

Accessibility

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.
Also make sure that the input masking on the ZIP field, which inserts a hyphen before the four-digit extension, is accessible to people using screen readers. We are using Filament Group's Politespace in the above demo.

Usability

When to use

When you need to be able to parse out the specific parts of a mailing address.

When to consider something else

If you need to collect addresses that may not fit this format (for example, international addresses).
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.

Guidance

Only label the optional inputs. Users can infer that all the others are required.
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.

Upgrading address forms (pre version 0.14.0)

The Design System previously leveraged Politespace as a way to implement input masking as part of this particular form template, specifically zip code inputs. Our guidance for upgrading is outlined in the following steps:

Be sure to include jQuery with your assets and include it onto your page.
Add the required Politespace files with your other 3rd party assets.
Follow the Politespace documentation on how to implement with your form fields.

For any questions or support, please feel free to reach out to the team at uswds@gsa.gov.

A template for signing a user into a website or app

<form class="usa-form">
  <fieldset>
    <legend class="usa-drop_text">Sign in</legend>
    <span>or <a href="javascript:void(0);">create an account</a></span>

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

    <label for="password-sign-in">Password</label>
    <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 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>

Documentation

Accessibility

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.
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.

Usability

When to use

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

When to consider something else

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.

Guidance

Less is more — make your explanations concise. Users sign in faster when less text surrounds the form.
Allow people to use their email address to sign in. People have an easier time remembering their email address than they do a unique username.
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 for users to retrieve a forgotten username and password. 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.
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.

Password reset form

A standard template for resetting a password

<form class="usa-form">
  <fieldset>
    <legend class="usa-drop_text">Reset password</legend>
    <span class="usa-serif">Please enter your new password</span>

    <div class="usa-alert usa-alert-info">
      <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 for="password-reset">New password</label>
    <input id="password-reset" name="password" type="password" />

    <label for="confirmPassword">Confirm password</label>
    <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 type="submit" value="Reset password" />
  </fieldset>
</form>

Documentation

Accessibility

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.

Usability

When to use

To offer a way to easily reset a password any time users are able to sign in to your site.

Guidance

If users need a password to access your site, they will forget that password and need a way to reset it.
For guidance on the technical details of validation, see the validation documentation.
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.
For more guidance on password requirements, see NIST's Appendix A—Strength of Memorized Secrets.

Form templates

Accessibility

Supporting screen readers

Known issues

Name form

Accessibility

Usability

When to use

When to consider something else

Guidance

Address form

Accessibility

Usability

When to use

When to consider something else

Guidance

Upgrading address forms (pre version 0.14.0)

Password reset form

Password information

Accessibility

Usability

When to use

Guidance

Running into an issue?

Engage with the community

Reach the team

Accessibility

Supporting screen readers

Known issues

Name form

Accessibility

Usability

When to use

When to consider something else

Guidance

Address form

Accessibility

Usability

When to use

When to consider something else

Guidance

Upgrading address forms (pre version 0.14.0)

Sign-in form

Accessibility

Usability

When to use

When to consider something else

Guidance

Password reset form

Password information

Accessibility

Usability

When to use

Guidance