WAI-ARIA Authoring Practices Guide
Accessibility
made simple.
Learn WAI-ARIA APG (Authoring Practices Guide) patterns with live demos, Good / Bad comparisons, and keyboard/ARIA references. Understand the "why" behind accessible implementations.
This site is for developers who write HTML/CSS/JavaScript and for anyone reviewing UI for accessibility.
Interactive Demos
Try components with a keyboard or screen reader to understand the difference firsthand.
Good / Bad Comparison
See common mistakes side-by-side with recommended implementations to understand what goes wrong and why.
Implementation Checklist
Each pattern includes a ready-to-use checklist for code reviews.
Recent Changes
Tracking the latest changes to the W3C APG.
1.4.11: Clarify the exemption "carries over" to UI components
The Understanding document for SC 1.4.11 Non-text Contrast was substantially reorganized, and now states normatively that when a graphic covered by the "essential" exception -- such as a logo -- also acts as a user interface component (e.g. a link or button), the exemption carries over to that component. It also notes, as a recommended practice, that authors should still provide another way to identify the component, and that other aspects of the criterion, such as a sufficiently contrasting focus indicator, remain required. No changes were needed to this site’s data.
PR #5250(opens in a new tab)3.2.4: Revise Understanding, clarify context-appropriate label differences are allowed
The Understanding document for SC 3.2.4 Consistent Identification was substantially rewritten. It clarifies that components with the same functionality don't need identical labels or icons -- contextual variation such as "Page 4" becoming "Previous page" (when viewed from page 5) is acceptable -- while using different icons for the same functionality is now listed as a new failure example, and buttons with different functions (such as separate "print receipt" / "print invoice" buttons) are explicitly out of scope. The PR states this does not change the criterion's normative meaning. No changes were needed to this site’s data.
PR #5251(opens in a new tab)1.3.5: Clarify whether the browser actually autofills is irrelevant
The Understanding document for SC 1.3.5 Identify Input Purpose now clarifies that whether a browser actually autofills a field is irrelevant to conformance -- what matters is whether the input’s purpose is programmatically determinable. It also notes that browsers autofilling via heuristics (rather than a programmatically exposed purpose) does not satisfy the criterion, and that autofill can be turned off in the browser while still exposing the purpose via the autocomplete attribute. No changes were needed to this site’s data.
PR #5293(opens in a new tab)
All Patterns
Pick any pattern that interests you. Patterns marked "Coming soon" will be published gradually.
Show/Hide & Expand
Notifications & Dialogs
Alert
AvailableA notification that immediately announces important messages via a live region without moving focus.
Dialog (Modal)
AvailableA dialog that renders in the foreground while making the background inert. Requires a focus trap and Escape key to close.
Alert and Message Dialogs
AvailableA dialog that requires the user to confirm or respond, such as "Are you sure you want to delete?"
Navigation
Breadcrumb
AvailableNavigation showing the current location within a site. Uses nav, a list structure, and aria-current for the current page.
Menu and Menubar
AvailableAn application-style menu built with role="menu" and related roles, navigated using arrow keys.
Menu Button
AvailableA button that opens a menu on activation. Uses aria-haspopup and aria-expanded to convey the relationship.
Link
AvailableThe fundamental yet nuanced link. Explains why you should use the a element instead of a div with onclick.
Landmarks
AvailableDivides the page into regions using header, nav, main, footer, etc., enabling quick navigation for assistive technologies.
Forms & Input
Button
AvailableThe most fundamental control. Covers the built-in accessibility the button element provides and the pitfalls of custom implementations.
Checkbox
AvailableAn on/off selection control. Also covers handling the indeterminate (mixed) state.
Radio Group
AvailableSelects one option from many. A prime example of arrow key navigation with roving tabindex.
Switch
AvailableAn on/off toggle. Covers the difference from checkbox and how to use role="switch".
Combobox
AvailableA text input combined with a suggestion list (autocomplete). One of the most complex patterns in the APG.
Listbox
AvailableSelecting from a list of options. Supports single and multi-select with arrow key navigation.
Slider
AvailableSelects a value from a range. Uses aria-valuenow/min/max with keyboard operation.
Slider (Multi-Thumb)
AvailableRange selection such as price ranges. Key considerations include thumb interaction constraints and labeling.
Spinbutton
AvailableA numeric input that increments and decrements via Up/Down keys or buttons, with range announcements.
Meter
AvailableA read-only indicator showing a quantity within a known range, such as disk usage.
Tabs & Toolbars
Data Display
Table
AvailableTabular data. Properly associating the table element with header cells is key for screen reader announcement.
Grid
AvailableAn interactive table (data grid) where individual cells are keyboard-navigable.
Treegrid
AvailableA grid with expandable and collapsible rows. A composite of tree and grid patterns.
Tree View
AvailableDisplays a hierarchical structure. Supports expand/collapse and navigation similar to a folder tree.
Feed
AvailableMakes an infinitely scrolling article list navigable and readable with assistive technologies.
Others
Carousel
AvailableAutomatically rotating slides. Play/pause controls and screen reader considerations are essential.
Tooltip
UpdatedAvailableSupplementary text that appears on focus or hover. Uses aria-describedby with keyboard support.
Window Splitter
AvailableA resize handle that moves the boundary between two panes via drag or keyboard.