Components

Input prefix or suffix

Use input prefixes and suffixes to show symbols or abbreviations that help users enter the right type of information in a form’s text input.

Credit card number

Credit card number (Error)

Weight, in pounds

lbs.

<form class="usa-form">
  <label class="usa-label" for="example-input-prefix">Credit card number</label>
  <div class="usa-input-group">
    <div class="usa-input-prefix" aria-hidden="true">
      <svg aria-hidden="true" role="img" focusable="false" class="usa-icon">
        <use xlink:href="/assets/img/sprite.svg#credit_card"></use>
      </svg>
    </div>
    <input
      id="example-input-prefix"
      class="usa-input"
      pattern="[0-9]*"
      inputmode="numeric"
    />
  </div>
  <label class="usa-label" for="example-input-prefix-error"
    >Credit card number (Error)</label
  >
  <div class="usa-input-group usa-input-group--error">
    <div class="usa-input-prefix" aria-hidden="true">
      <svg aria-hidden="true" role="img" focusable="false" class="usa-icon">
        <use
          xmlns:xlink="http://www.w3.org/1999/xlink"
          xlink:href="/assets/img/sprite.svg#credit_card"
        ></use>
      </svg>
    </div>
    <input
      id="example-input-prefix-error"
      class="usa-input"
      pattern="[0-9]*"
      inputmode="numeric"
    />
  </div>
</form>
<form class="usa-form">
  <label class="usa-label" for="example-input-suffix">Weight, in pounds</label>
  <div class="usa-input-group usa-input-group--sm">
    <input
      id="example-input-suffix"
      class="usa-input"
      pattern="[0-9]*"
      inputmode="numeric"
    />
    <div class="usa-input-suffix" aria-hidden="true">lbs.</div>
  </div>
</form>

<form class="usa-form">
  <label class="usa-label" for="example-input-prefix">Credit card number</label>
  <div class="usa-input-group">
    <div class="usa-input-prefix" aria-hidden="true">
      <svg aria-hidden="true" role="img" focusable="false" class="usa-icon">
        <use xlink:href="/assets/img/sprite.svg#credit_card"></use>
      </svg>
    </div>
    <input
      id="example-input-prefix"
      class="usa-input"
      pattern="[0-9]*"
      inputmode="numeric"
    />
  </div>
  <label class="usa-label" for="example-input-prefix-error"
    >Credit card number (Error)</label
  >
  <div class="usa-input-group usa-input-group--error">
    <div class="usa-input-prefix" aria-hidden="true">
      <svg aria-hidden="true" role="img" focusable="false" class="usa-icon">
        <use
          xmlns:xlink="http://www.w3.org/1999/xlink"
          xlink:href="/assets/img/sprite.svg#credit_card"
        ></use>
      </svg>
    </div>
    <input
      id="example-input-prefix-error"
      class="usa-input"
      pattern="[0-9]*"
      inputmode="numeric"
    />
  </div>
</form>
<form class="usa-form">
  <label class="usa-label" for="example-input-suffix">Weight, in pounds</label>
  <div class="usa-input-group usa-input-group--sm">
    <input
      id="example-input-suffix"
      class="usa-input"
      pattern="[0-9]*"
      inputmode="numeric"
    />
    <div class="usa-input-suffix" aria-hidden="true">lbs.</div>
  </div>
</form>

Guidance

When to use the input prefix or suffix component

• Highlight the type of information. Prefixes and suffixes are useful when there’s a commonly understood symbol or abbreviation for the type of information the user needs to enter. Some common examples include units of measurement (like lbs or ft), symbols (like $ or %), or even icons (like showing an eye for password visibility).

• Input cannot include units. Use prefixes and suffixes if the input refers to a unit or currency amount (like a length or dollar amount), but the user’s input must include digits only, not units or a currency symbol.

• Reduce mental load. Adding a prefix or suffix can help the user more quickly understand what kind of information is requested.

When to consider something else

• Open-ended form fields. If there aren’t specific parameters around the information the user needs to enter, a prefix or suffix may be incorrect. For example, don’t use a $ prefix for a form field asking “What’s a fair resolution?” if the user could enter either “$1,000” or “a full refund” as the answer.

• Explanation requires additional words. Don’t use prefixes or suffixes if a symbol or abbreviation is insufficient to convey the meaning. There shouldn’t be any confusion between what type of information a prefix or suffix represents. This is especially true when using icons that could have multiple meanings.

Usability guidance

• Follow best practices when using an icon. If you include an icon as a prefix or suffix, follow the design system’s icon guidance.

• Use common abbreviations. Only use commonly understood abbreviations when indicating a text prefix or suffix. Don’t use the full word.

Accessibility guidance

• Hide from screen readers. Prefixes and suffixes are hidden from screen readers using aria-hidden.

• Use descriptive labels. Labels should clearly indicate what type of data to enter since prefixes and suffixes are hidden from screen readers. For example, if you’re requesting someone’s height in inches, you have “in.” appear in a suffix, but your form label should say “Height, in inches.”

Using the input prefix or suffix component

• Placement matters. Place the .usa-input-prefix element before the .usa-input element, and place the .usa-input-suffix element after .usa-input. Both elements should be placed inside .usa-input-group.

• Use text or icons. Input prefixes and suffixes can accept either plain text or icons.

• Use validation styles. Place input validation classes on usa-input-group.

Input prefix or suffix settings

This component has no settings.

Input prefix or suffix variants

Variant	Description
.usa-input-group--error	Displays an input group error state.
.usa-input-group--success	Displays an input group success state.
.usa-input-group--[width]	Displays an input group at a specific width. Accepts 2xs (5ex), xs (9ex), sm or small (13ex), md or medium (20ex), lg (30ex), xl (40ex), and 2xl (50ex).

Package

• Package usage: @forward "usa-input-prefix-suffix";
• Dependencies: usa-input, usa-icon

Latest updates

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

Date	USWDS version	Affects	Breaking	Description
2023-11-20	N/A	Guidance	No	Added documentation for usa-input-group--success variant. More information: uswds-site#2162
2023-06-09	3.5.0	Accessibility Styles	No	Improved consistency and visibility of disabled styles. Form elements with the disabled or aria-disabled attribute now get consistent styling and have proper color contrast. More information: uswds#5063
2023-06-09	3.5.0	Accessibility Styles	No	Improved consistency of disabled styles in forced colors mode. More information: uswds#5295
2022-04-28	N/A	Guidance	No	Updated package name to usa-input-prefix-suffix. More information: uswds-site#1538
2022-04-28	3.0.0	Assets JavaScript Styles	Breaking	Breaking Updated to Sass module syntax and new package structure. More information: uswds#4656
2022-04-13	N/A	Guidance	No	Updated package name to form-controls. More information: uswds-site#1497
2021-03-18	N/A	Guidance	No	Clarified that the input cannot include units. More information: uswds-site#1186
2021-03-17	N/A	Guidance	No	Added input prefix or suffix documentation. More information: uswds-site#1180
2021-03-17	2.11.0	Guidance JavaScript Markup Styles	No	Added input prefix or suffix component. Use input prefixes and suffixes to show symbols or abbreviations that help users enter the right type of information in a form’s text input. More information: uswds#3999