Skip to main content

Complex Form

The complex form template provides patterns for lengthy forms that benefit from being broken into multiple steps or sections, helping users complete tasks without feeling overwhelmed.


Overview

Complex forms are multi-step or multi-section forms designed to collect a significant amount of information from users. By breaking lengthy forms into logical sections with clear progress indicators, users can complete tasks more efficiently while reducing cognitive load and form abandonment rates.

This template combines several USWDS components including the step indicator, fieldsets with legends, form inputs, validation patterns, and navigation controls to create an accessible, user-friendly form experience.


Key Elements

Step Indicator

The step indicator shows users their progress through a multi-step form, helping them understand where they are and how much remains.

Component Preview

  1. Personal information completed
  2. Contact details current step
  3. Review and submit not completed

Step 2 of 3 Contact details


Component Code

<div class="usa-step-indicator" aria-label="progress">
  <ol class="usa-step-indicator__segments">
    <li class="usa-step-indicator__segment usa-step-indicator__segment--complete">
      <span class="usa-step-indicator__segment-label">Personal information <span class="usa-sr-only">completed</span></span>
    </li>
    <li class="usa-step-indicator__segment usa-step-indicator__segment--current" aria-current="true">
      <span class="usa-step-indicator__segment-label">Contact details <span class="usa-sr-only">current step</span></span>
    </li>
    <li class="usa-step-indicator__segment">
      <span class="usa-step-indicator__segment-label">Review and submit <span class="usa-sr-only">not completed</span></span>
    </li>
  </ol>
  <div class="usa-step-indicator__header">
    <h2 class="usa-step-indicator__heading">
      <span class="usa-step-indicator__heading-counter">
        <span class="usa-sr-only">Step</span>
        <span class="usa-step-indicator__current-step">2</span>
        <span class="usa-step-indicator__total-steps">of 3</span>
      </span>
      <span class="usa-step-indicator__heading-text">Contact details</span>
    </h2>
  </div>
</div>

Fieldsets with Legends

Use fieldsets and legends to group related form fields, providing clear context and improving accessibility for screen reader users.

Component Preview

Personal Information
For example: 04 28 1986

Component Code

<fieldset class="usa-fieldset">
  <legend class="usa-legend usa-legend--large">Personal Information</legend>

  <label class="usa-label" for="first-name">First name <span class="text-secondary-dark">*</span></label>
  <input class="usa-input" id="first-name" name="first-name" type="text" required>

  <label class="usa-label" for="last-name">Last name <span class="text-secondary-dark">*</span></label>
  <input class="usa-input" id="last-name" name="last-name" type="text" required>

  <label class="usa-label" for="dob">Date of birth</label>
  <div class="usa-hint" id="dob-hint">For example: 04 28 1986</div>
  <div class="usa-memorable-date">
    <div class="usa-form-group usa-form-group--month">
      <label class="usa-label" for="dob-month">Month</label>
      <input class="usa-input usa-input--inline" id="dob-month" name="dob-month" type="text" maxlength="2" pattern="[0-9]*" inputmode="numeric">
    </div>
    <div class="usa-form-group usa-form-group--day">
      <label class="usa-label" for="dob-day">Day</label>
      <input class="usa-input usa-input--inline" id="dob-day" name="dob-day" type="text" maxlength="2" pattern="[0-9]*" inputmode="numeric">
    </div>
    <div class="usa-form-group usa-form-group--year">
      <label class="usa-label" for="dob-year">Year</label>
      <input class="usa-input usa-input--inline" id="dob-year" name="dob-year" type="text" minlength="4" maxlength="4" pattern="[0-9]*" inputmode="numeric">
    </div>
  </div>
</fieldset>

Navigation Controls

Provide clear navigation between form steps with Previous, Next, and Submit buttons. Always allow users to go back and review or edit previous sections.

Component Preview


Component Code

<ul class="usa-button-group">
  <li class="usa-button-group__item">
    <button type="button" class="usa-button usa-button--outline">Back</button>
  </li>
  <li class="usa-button-group__item">
    <button type="button" class="usa-button">Continue</button>
  </li>
</ul>

Form Validation

Display inline error messages to help users correct mistakes before proceeding to the next step. Validation should occur on blur or form submission.

Component Preview

Please enter a valid email address

Component Code

<div class="usa-form-group usa-form-group--error">
  <label class="usa-label usa-label--error" for="email-error">Email address <span class="text-secondary-dark">*</span></label>
  <span class="usa-error-message" id="email-error-message" role="alert">Please enter a valid email address</span>
  <input class="usa-input usa-input--error" id="email-error" name="email-error" type="email" aria-describedby="email-error-message" value="invalid-email">
</div>


Guidance

When to use the complex form template

Forms with more than 5-7 fields.
Long forms benefit from being broken into smaller, manageable sections that reduce cognitive load.
Forms with logically distinct sections.
When your form naturally divides into categories like personal information, contact details, and payment information.
Forms that require significant user input.
Applications, registrations, or transactions that collect substantial data from users.
Forms where users may need to gather information.
When users might need to look up account numbers, reference documents, or consult with others to complete the form.

Best practices

Save user progress automatically.
Allow users to return and complete forms later without losing their work. Display a clear indicator when progress is saved.
Allow back navigation.
Users should always be able to return to previous steps to review or edit their responses.
Provide clear progress indication.
Use the step indicator component to show users where they are in the process and how many steps remain.
Group related fields logically.
Use <fieldset> and <legend> elements to group related form controls and provide context.
Validate inline when possible.
Provide immediate feedback on field validation rather than waiting until form submission.
Include a review step.
Allow users to review all entered information before final submission.

Accessibility considerations

Use <fieldset> and <legend> for grouping.
Screen readers announce the legend text when users enter the fieldset, providing important context for the group of fields.
Announce errors to screen readers.
Use role="alert" or aria-live="polite" on error messages so they are announced when they appear.
Manage focus appropriately.
When moving between steps, set focus to the first form element or the step heading. When displaying errors, move focus to the error summary or first error field.
Associate error messages with fields.
Use aria-describedby to connect error messages to their corresponding form inputs.
Indicate required fields clearly.
Mark required fields with both visual indicators and the required attribute for programmatic indication.
Provide clear labels and instructions.
Every form field should have a visible label. Use hint text to provide formatting examples or additional context.

USWDS Documentation

For more guidance, view the USWDS Form Templates Documentation.

Looking for U.S. government information and services?
Visit USA.gov