CoCreate-aria

Orchestrate dynamic UI behavior and ARIA state with event-driven action chains, configured via HTML5 attributes or the JavaScript API. Take it for a spin in our playground!

Docs & Demo

For a complete guide and working demo refer to the doumentation

CDN

<script src="https://cdn.cocreate.app/aria/latest/CoCreate-aria.min.js"></script>

<script src="https://cdn.cocreate.app/aria/latest/CoCreate-aria.min.css"></script>

NPM

$ npm i @cocreate/aria

yarn

$ yarn install @cocreate/aria

Table of Contents

• Table of Contents
• Announcements
• Roadmap
• How to Contribute
• About
• License

Announcements

All updates to this library are documented in our CHANGELOG and releases. You may also subscribe to email for releases and breaking changes.

Roadmap

If you are interested in the future direction of this project, please take a look at our open issues and pull requests. We would love to hear your feedback.

About

CoCreate-aria is guided and supported by the CoCreate Developer Experience Team.

Please Email the Developer Experience Team here in case of any queries.

CoCreate-aria is maintained and funded by CoCreate. The names and logos for CoCreate are trademarks of CoCreate, LLC.

How to Contribute

We encourage contribution to our libraries (you might even score some nifty swag), please see our CONTRIBUTING guide for details.

We want this library to be community-driven, and CoCreate led. We need your help to realize this goal. To help make sure we are building the right things in the right order, we ask that you create issues and pull requests or merely upvote or comment on existing issues or pull requests.

We appreciate your continued support, thank you!

License

The MIT License (MIT)

Toggle buttons and selection groups

Use aria-pressed on a button for an independent toggle. Related toggles can sit inside role="group"; grouping does not make them mutually exclusive.

<div role="group" aria-label="Text formatting">
    <button type="button" aria-pressed="false">Bold</button>
    <button type="button" aria-pressed="false">Italic</button>
</div>

For one selected option, use custom radios inside a labelled radiogroup. These controls do not need aria-controls or a panel to display.

<div role="radiogroup" aria-label="API category">
    <button type="button" role="radio" aria-checked="true">All</button>
    <button type="button" role="radio" aria-checked="false">Storage</button>
    <button type="button" role="radio" aria-checked="false">Cloud</button>
</div>

Activating a radio selects it and deselects its siblings. Arrow keys move and select, Home/End jump to the first/last available item, and Space/Enter activate. Inside a toolbar, arrow keys move focus without selecting. Nested radio groups are independent. Disabled and hidden items are skipped during group navigation.

Custom role="checkbox" and role="switch" controls toggle aria-checked. Native checkbox and radio inputs retain native behavior. Toggle and custom checked controls synchronize their active class with the state attribute; external attribute changes and dynamically inserted controls are supported. An initial mixed state is preserved until activation, which selects true.

Controls handled by this module block activation when disabled or when aria-disabled="true". Existing tab panel behavior continues to use aria-selected with its tablist and aria-controls targets.

CoCreate links selection controls that reference the same aria-controls target. Clicking a custom radio clears linked pressed/checked controls; activating a linked toggle clears the radios while preserving other toggles. Mark a radio with aria-default="true" (or an empty aria-default) to select it when the last toggle is cleared. Without a default, all controls may remain unselected. aria-default="false" disables fallback; disabled radios are not eligible. If multiple eligible defaults are declared, no fallback is selected. aria-checked describes current selection independently of this default. aria-default is a CoCreate extension, not a standard ARIA attribute. This is CoCreate behavior, not native ARIA grouping. Tabs and disclosure controls remain separate, and the target's visibility is unchanged.

Use aria-default="next" for a moving default. Its initial radio is the starting fallback. Selecting another radio sharing the controlled target removes the marker from the previous radio and places it on the selected one. "Next" means the next radio selected by the user, including keyboard activation, not the next radio in DOM order. Pressed buttons and checked toggles never receive or move this marker. Clearing the last toggle returns to the radio currently carrying it. A fixed aria-default="true" does not move. Declare one default per linked set; use either a fixed or a moving default. The marker lives in DOM attributes and is not automatically persisted across reloads. Direct changes to aria-checked do not transfer it.

<div role="group" aria-label="Results mode">
    <div role="radiogroup" aria-label="Preset">
        <button role="radio" aria-checked="true" aria-controls="results" aria-default="next">All</button>
        <button role="radio" aria-checked="false" aria-controls="results">Recommended</button>
    </div>
    <button aria-pressed="false" aria-controls="results">Storage</button>
    <button aria-pressed="false" aria-controls="results">Cloud</button>
</div>
<div id="results"></div>

Native input[type="radio"] and input[type="checkbox"] with aria-controls also participate in linked selection and fixed/moving defaults. They use their native checked property and keyboard behavior, without redundant aria-checked or aria-pressed attributes. When coordination changes another native input, CoCreate dispatches input and change after the linked values are updated; unselected radios do not dispatch these notifications.

Multiselectable grids

An element with role="grid" aria-multiselectable="true" scopes selection to its descendant rows. Mark selectable rows with role="row" and aria-selected="false"; include a gridcell in each row. Native table, tr, and td elements provide the corresponding row and cell structure. The module sets one row in the grid's tab sequence and leaves selection on the row's aria-selected attribute so other actions can query it directly.

<div role="grid" aria-label="Files" aria-multiselectable="true">
    <div role="row" aria-selected="false">
        <div role="gridcell">Document A</div>
    </div>
    <div role="row" aria-selected="false">
        <div role="gridcell">Document B</div>
    </div>
</div>

Click selects one row; Control/Command-click toggles one row; Shift-click selects a range; and Control/Command-Shift-click adds a range. Arrow keys and Home/End move focus without changing selection. Space toggles the focused row, Shift with an arrow extends selection, Control/Command-A selects the loaded rows, and Escape clears them. These interactions do not activate links or other controls inside a row. Selection actions are scoped to the nearest grid.

A grid row can instead contain a native checkbox. Its own checked state is the selection state; the row does not need aria-selected. Checkbox clicks toggle independently, including Control/Command-click. Shift-click applies the clicked checkbox's new state to the range since the last checkbox click. Checkboxes with the same name form a range within one grid. CoCreate Aria does not synchronize checkbox checked with row aria-selected; an app can bind them explicitly when it needs both.