Description

Improved reader experience. Character count now includes a brief pause on input before announcing the status. Based on recommendations from our friends at GovUK! Closes #4714.

Preview

Character count preview →

Additional information

Screen reader experience is improved as they're no longer bombarded by constant updates or have their announcements cutoff by the updated status.

New markup

<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" 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">25 characters allowed</span>
+  <span id="with-hint-input-info" class="usa-character-count__message">You can enter up to 25 characters</span>
+ <!-- After init() -->
+  <div class="usa-character-count__status usa-hint" aria-hidden="true">25 characters allowed</div>
+  <div class="usa-character-count__sr-status usa-sr-only" aria-live="polite">25 characters allowed</div>
+ <!-- /After init() -->
  </div>

The usa-hint class has been removed and is now applied to the new dynamic element usa-character-count__status.

Character count's screen reader counterpart (usa-character-count__sr-status) updates and announces after a 1000ms delay.

User required changes

None. The new status messages are dynamic. Older character count message markup will update on enhance see character-count js lines 159-161

  // Hide hint and remove aria-live for backwards compatibility
  messageEl.classList.add("usa-sr-only");
  messageEl.removeAttribute("aria-live");

Also included

• Hint no longer gives status on input [1257621, 1083fd7]
• Two new status messages (visual & screen reader) are created dynamically [e1443f4]
• Created a new function to run on init enhanceCharacterCount
• Added debounce utility to delay screen reader status
• Added JSDoc comments to all JS functions in character count
• Updated unit tests
  • Use new status message class (previously usa-character-count__message)
  • Add test for hiding requirement for visual users
  • Add test for validating creation of visual status message
  • Add test for validating creation of screen reader status message

How to test

• Character count should visually look and function the same
• Character count on screen reader should:
  • Announce the requirements (You can enter up to 25 characters)
  • Announce how many characters are left after user input

Before you hit Submit, make sure you’ve done whichever of these applies to you:

• Follow the 18F Front End Coding Style Guide and Accessibility Guide.
• Run npm test and make sure the tests for the files you have changed have passed.
• Run your code through HTML_CodeSniffer and make sure it’s error free.
• Title your pull request using this format: [Website] - [UI component]: Brief statement describing what this pull request solves.