fix(pagination): add aria attributes for screen reader accessibility

[msmps]

Description

• Wrap pagination controls in <nav aria-label="Pagination">
• Add aria-live="polite" and aria-atomic="true" to "Showing X-Y of Z" text for page change announcements
• Add navigation to PaginationLabels for i18n support
• Resolves WCAG 2.1 SC 1.3.1 (Info and Relationships) and SC 4.1.3 (Status Messages) violations

Problem

1. Controls were wrapped in a generic <div>
2. The "Showing X-Y of Z" status text wasn't announced when pages changed

Solution

Add semantic HTML and ARIA attributes:

• <nav aria-label={labels.navigation}> (defaults to "Pagination", customizable for i18n)
• aria-live="polite" - Announces page range changes without interrupting user
• aria-atomic="true" - Ensures the entire status text is announced as a whole

Testing

Verified with VoiceOver on macOS:

1. Enable VoiceOver (Cmd + F5)
2. Use rotor (Ctrl + Option + U) to open landmarks menu
3. Confirm "Pagination, navigation" appears in the list
4. Navigate between pages and confirm "Showing X-Y of Z" is announced

---

• Reviews
  • bonk has reviewed the change
  • automated review not possible because: accessibility/ARIA changes require manual screen reader testing
• Tests
  • Tests included/updated
  • Automated tests not possible - manual testing has been completed as follows: VoiceOver testing on macOS as described above
  • Additional testing not necessary because:

[pkg-pr-new]

npm i https://pkg.pr.new/@cloudflare/kumo@47

commit: 73f3ee2

[mattrothenberg]

@msmps small merge conflict in this one FYI

[github-actions]

Docs Preview

View docs preview

Commit: 73f3ee2

[github-actions]

Visual Regression Report — 9 changed, 2 unchanged

9 screenshot(s) with visual changes:

Pagination / Pagination Basic

278 px (0.27%) changed

Before	After	Diff

Pagination / Pagination Full

259 px (0.26%) changed

Before	After	Diff

Pagination / Pagination Simple

456 px (0.45%) changed

Before	After	Diff

Pagination / Pagination Mid Page

534 px (0.53%) changed

Before	After	Diff

Pagination / Pagination Custom Text

691 px (0.68%) changed

Before	After	Diff

Pagination / Pagination Custom Page Size Options

722 px (0.71%) changed

Before	After	Diff

Pagination / Pagination Compound Custom Info

240 px (0.24%) changed

Before	After	Diff

Pagination / Pagination Page Size Right

407 px (0.4%) changed

Before	After	Diff

Pagination / Pagination I18n

568 px (0.56%) changed

Before	After	Diff

2 screenshot(s) unchanged

• Pagination / Pagination Large Dataset
• Pagination / Pagination Page Size Selector

---

Generated by Kumo Visual Regression

[geoquant]

// instead of:
<div role="status" aria-live="polite" className="...">

// use:
<div aria-live="polite" aria-atomic="true" className="...">

[stritt]

/bonk please review

[ask-bonk]

@stritt Bonk workflow was cancelled.

View workflow run · To retry, trigger Bonk again.

[stritt]

/bigbonk your turn to review

[ask-bonk]

Good accessibility improvement overall — wrapping controls in <nav> and adding aria-live for status announcements are the right moves. However, the aria-live / aria-atomic attributes are only applied in the legacy rendering path. The compound component Pagination.Info (the recommended API) doesn't get the same treatment, which means most new consumers won't benefit from this fix.

Specifically, the PaginationInfo component (line ~117-124) renders a plain <div> without aria-live or aria-atomic. Since the compound API is the recommended approach going forward, that's the more important place to add these attributes:

// In PaginationInfo (~line 118)
<div
  data-slot="pagination-info"
  aria-live="polite"
  aria-atomic="true"
  className={cn("text-sm text-kumo-strong", className)}
>

Also, to answer the question in the PR description: yes, <nav> is preferred over <div role="navigation"> — using semantic HTML is the right call here.

[ask-bonk]

Review submitted successfully. Here's a summary of what I flagged:

Request Changes on PR #47 with two key points:

1. Main issue: Compound Pagination.Info missing ARIA attributes — The aria-live="polite" and aria-atomic="true" attributes were only added to the legacy rendering path (line 519-521). The compound PaginationInfo component (~line 118), which is the recommended API for new code, still renders a plain <div> without these attributes. Most consumers using the modern API won't get screen reader announcements.

2. Minor consideration on <nav> labeling — If multiple Pagination instances exist on the same page (e.g. top/bottom of a table), they'll produce duplicate <nav aria-label="Pagination"> landmarks. Suggested considering an optional aria-label prop on PaginationControls for differentiation in a follow-up.

I also confirmed that <nav> is the right choice over <div role="navigation"> as the PR author asked.

github run

[stritt]

looks good, thanks for addressing the feedback! 👍

nope