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.

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

Name form

A standard template for collecting a person’s full name

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>

Accessibility

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

Accessibility

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.

Sign-in form

A template for signing a user into a website or app

Sign in or create an account

Show password

Forgot username?

Forgot password?

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

Accessibility

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

Reset password Please enter your new password

Password information

Length requirements
Character constraints, if any

Show my typing

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

Accessibility

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.