results-description.md

Text describing how many results are being shown.

Structure

The implementation should follow this format:

• Showing 1–10 of 999 for "[query]"
  • When used in non-search contexts, omit the for "[query]" portion.
  • If a filter is applied to the results, add "with X filters applied" to the end. This is not necessary when sorting is applied since the Sort component itself acts as the visual indicator.

Code guidance

• An <h2> is not required for the results description. Some implementations on VA.gov may use this convention, but this is discouraged. A stable, targetable element (e.g., ID) is sufficient for focus management.
• Using role="status" provides an implicit aria-live="polite", which will announce updates when the content changes. Adding an explicit aria-live is not necessary.
• To support programmatic focus, tabindex="-1" is required if we intend to move focus to the results description element. This is a focus-driven announcement pattern and is separate from live region behavior.
• When moving focus to the results description, the content should be announced as a single unit, assuming the DOM update is atomic. In testing (especially with VoiceOver), inline elements such as <strong>, <span>, etc., can cause the content to be announced in fragmented chunks instead of a single cohesive sentence, even though this is not consistently expected behavior.
• Avoid inline stylistic elements within the results description when possible, and instead rely on plain text to ensure consistent, single-pass announcements across assistive technologies. If inline styling is required, additional measures such as aria-atomic="true" may help, but results can still vary across screen readers.