Root
[data-a11y-scroll-cue]
Wraps the scrollport and receives lifecycle state.
Real-world example · SaaS control room
Audit findings without losing the last columns
An accessibility lead is reviewing a release queue on a narrow screen. A11y Scroll Cue makes the table’s horizontal overflow visible and gives keyboard users a temporary tab stop only when it is needed.
Scenario
Release review at tablet width
The lead needs to compare ownership, severity, evidence, and release status without hiding table columns or replacing the semantic table with a custom grid.
User goal
Reach the audit queue with the keyboard, discover that more columns are available, review them with native scrolling, and restore the cue for another tester.
Try it
Test the complete state change
- Narrow the viewport until the queue overflows and the text cue appears.
- Press Tab until the table region receives focus, then use ArrowLeft and ArrowRight.
- Scroll horizontally and confirm that the cue moves to its dismissed state.
- Activate Show cue again and check that focus stays on the button while the visible status text updates.
Live example
Release accessibility queue
Four unresolved findings are ready for triage. The status line describes the demo state without making the plugin cue itself a live region.
The cue is ready. Horizontal scrolling will dismiss it.
| Finding | Journey | Severity | Owner | Evidence | Target | Release status |
|---|---|---|---|---|---|---|
| A11Y-142 | Payment method | High | Checkout UI | Keyboard focus skips the saved-card error summary. | 29 July | Fix in review |
| A11Y-158 | Address lookup | Medium | Forms | Suggestion count is not announced after filtering. | 30 July | Test pending |
| A11Y-161 | Order review | High | Design system | Focus indicator is clipped at 200% zoom. | 29 July | Fix in progress |
| A11Y-169 | Confirmation | Medium | Notifications | Success heading is not programmatically focused. | 31 July | Owner assigned |
Accessibility notes
What this example preserves
- The queue remains a native table with a caption, scoped headers, and useful text in every status cell.
-
The plugin adds
tabindex="0", a region role, and the supplied accessible name only while horizontal overflow exists. - Native browser keyboard scrolling is preserved; the plugin does not intercept arrow, Home, End, or Page keys.
-
describeScrollport: truelinks the visible cue text to the focused region. The separate status line reports reset and dismissal actions. - Focus stays on the reset button after activation, focus indicators remain visible, and both package and demo motion respect reduced motion preferences.
- Limitation: exact horizontal scrolling keys and screen reader announcements still depend on the browser, operating system, and assistive technology combination.
Developer notes
The copyable contract
Demo toolbar and status classes are page chrome. Only the
data-a11y-scroll-cue* attributes belong to the plugin
setup.
Child
[data-a11y-scroll-cue-scrollport]
The explicit element that owns native horizontal scrolling.
Options
Label + description
This demo sets regionLabel and opts into
describeScrollport.
CSS imports
import "a11y-scroll-cue/styles.css";Initialization
import { createA11yScrollCue } from "a11y-scroll-cue";
const root = document.querySelector("[data-a11y-scroll-cue]");
if (root instanceof HTMLElement) {
createA11yScrollCue(root, {
regionLabel: "Checkout release accessibility findings",
describeScrollport: true,
});
}