Character count

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

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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
<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-hint usa-character-count__message" aria-live="polite">
      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-hint usa-character-count__message" aria-live="polite">
      You can enter up to 50 characters
    </span>
  </div>
</form>

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

  • 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.
  • Use the aria-live attribute on character count message. Use aria-live="polite" so that updates to character count message are also announced when using a screen reader.

Implementation

  • 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.
  • Account for no-JavaScript environments. Add a default message in the message element that refers to the character limit. This will appear in instances when JavaScript does not load.

Package information

  • Package usage: @import form-controls
  • Requires: required, global