Components

Character count

Character count helps users know how much text they can enter when there is a limit on the number of characters.

Passed WCAG 2.1 AA

Testing has revealed some issues with this component. Learn more in the known issues section on this page.

This is an input with a character counter.
You can enter up to 25 characters
This is a textarea with a character counter.
You can enter up to 50 characters

<form class="usa-form">
  <div class="usa-character-count">
    <div class="usa-form-group">
      <label class="usa-label" for="with-hint-input">Text input</label>
      <span id="with-hint-input-hint" class="usa-hint"
        >This is an input with a character counter.</span
      >
      <input
        class="usa-input usa-character-count__field"
        id="with-hint-input"
        maxlength="25"
        name="with-hint-input"
        aria-describedby="with-hint-input-info with-hint-input-hint"
      />
    </div>
    <span id="with-hint-input-info" class="usa-character-count__message"
      >You can enter up to 25 characters</span
    >
  </div>
</form>
<form class="usa-form">
  <div class="usa-character-count">
    <div class="usa-form-group">
      <label class="usa-label" for="with-hint-textarea">Textarea</label>
      <span id="with-hint-textarea-hint" class="usa-hint"
        >This is a textarea with a character counter.</span
      >
      <textarea
        class="usa-textarea usa-character-count__field"
        id="with-hint-textarea"
        maxlength="50"
        name="with-hint-textarea"
        rows="5"
        aria-describedby="with-hint-textarea-info with-hint-textarea-hint"
      ></textarea>
    </div>
    <span id="with-hint-textarea-info" class="usa-character-count__message"
      >You can enter up to 50 characters</span
    >
  </div>
</form>

Guidance

When to use the character count component

  • Brevity is desired. When users are likely to provide more detail than is needed, and you want to force them to use fewer words. Note: this will likely increase the amount of time it takes users to submit the form because editing requires thinking. In the words of Mark Twain, “I didn’t have time to write a short letter, so I wrote a long one instead.”
  • Legal requirement. When there is a legal reason where an entry must be under a certain number of characters.

When to consider something else

  • Backend limitations. If your users keep hitting the character limit imposed by the backend of your service then try to increase the limit rather than use a character count.
  • Already implied. If the character length is apparent or implied by the data type (i.e. phone number or zip code).
  • Exceeding the character limit is highly unlikely. If the vast majority of users (well over 99%) are very unlikely to run afoul of backend validation, such as an address field that has a database field limit of 250 characters.

Accessibility guidance

Test the character count component in your own project.

USWDS tested the character count component for accessibility. You should test your implementation, too.

Use character count accessibility tests
  • Associate the character count message to the input. Use aria-describedby on the input to allow the message to be announced to those using screen readers.

Using the character count component

  • Add component classes. The structure should include a base element with the class usa-character-count. Inside of that base element there should be an input element (input or textarea) with the class usa-character-count__field and an message element (span or div) with the class usa-character-count__message.
  • Add a maxlength attribute to the input element. This will be used as the limit referenced in the message and for validation.
  • Provide a backup message for environments without JavaScript. In your markup, add a default message in the usa-character-count__message element that refers to the character limit. This will appear in instances when JavaScript does not load.

Character count settings

This component has no settings.

Character count variants

This component has no variants.

Accessibility test status

The USWDS team did 9 tests based on WCAG 2.1 AA success criteria.

Overview of recent accessibility test results:
Total tests
Passed
Passed with exceptions
Conditional
Failed
9 7 1 1 0

Overview of recent accessibility test results:

  • Passed: 7
  • Passed with exceptions: 1
  • Conditional: 1
  • Failed: 0

Learn more on the character count accessibility tests page.

Known issues

All known issues for character count are tracked in GitHub . Notable usability issues are tracked below:

  • Screen reader and screen magnifier users had trouble recognizing when they exceeded the character count limit. More information on GitHub: uswds#5574

Help fix these issues or add details on GitHub. Don't have an account? Please join our community to share feedback and contribute to USWDS.

Package

  • Package usage: @forward "usa-character-count";
  • Dependencies: uswds-core

Latest updates

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

Date USWDS version Affects Breaking Description
2024-10-04 3.9.0
  • JavaScript
  • Styles
No

Enhanced visual cue when maxlength is exceeded. Now, the component uses standard USWDS error styles to visually enhance the error state. More information: uswds#5908

2024-05-15 N/A
  • Guidance
No

Added WCAG compliance tag and accessibility test status section. More information: uswds-site#2607

2024-03-13 N/A
  • Guidance
No

Added known issues section. More information: uswds-site#2402

2023-11-20 N/A
  • Guidance
No

Removed note about adding aria-live to the markup. The aria-live attribute is now added dynamically. More information: uswds-site#2149

2023-11-20 N/A
  • Guidance
No

Added detail to the instructions for adding defaults for non-JavaScript environments. More information: uswds-site#2149

2022-10-19 3.2.0
  • Accessibility
  • JavaScript
  • Markup
  • Styles
No

Improved screen reader experience. The character counter now includes a brief pause after input before announcing how many characters remain. Announcing the input no longer prevents the character counter from reading. More information: uswds#4976

2022-04-28 3.0.0
  • Assets
  • JavaScript
  • Styles
Breaking

Breaking Updated to Sass module syntax and new package structure. More information: uswds#4656