Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(core): link Collapsible trigger to its content via aria-controls (#3707)

Baraa Hamodi36ecca556fa0
diff --git a/.changeset/collapsible-aria-controls.md b/.changeset/collapsible-aria-controls.md
new file mode 100644
index 0000000000..46193084e1
--- /dev/null
+++ b/.changeset/collapsible-aria-controls.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] Collapsible: link the trigger to its content region with `aria-controls`, and give the content region a matching `id`. Completes the disclosure pattern so assistive tech can move from the trigger button to the region it shows/hides (previously only `aria-expanded` was set). (#3707)
+@bhamodi
diff --git a/packages/core/src/Collapsible/Collapsible.tsx b/packages/core/src/Collapsible/Collapsible.tsx
index d41a0b50ff..939479a3ad 100644
--- a/packages/core/src/Collapsible/Collapsible.tsx
+++ b/packages/core/src/Collapsible/Collapsible.tsx
@@ -10,7 +10,8 @@
*
* Collapsible is a standalone primitive that makes any content collapsible.
* It renders a trigger area (always visible) and a content area that toggles.
- * Handles state management, accessibility (aria-expanded), and chevron indicator.
+ * Handles state management, accessibility (aria-expanded + aria-controls linking
+ * the trigger to its content region), and chevron indicator.
*
* Works standalone or coordinated by CollapsibleGroup via the `value` prop.
* When the surrounding CollapsibleGroup enables `dividers`, each Collapsible
@@ -26,7 +27,7 @@
* - /packages/cli/templates/blocks/components/Collapsible/ (showcase blocks)
*/
-import {use, type ReactNode} from 'react';
+import {use, useId, type ReactNode} from 'react';
import * as stylex from '@stylexjs/stylex';
import {
borderVars,
@@ -239,6 +240,10 @@ export function Collapsible({
const chevronIcon = getIcon('chevronDown');
+ // Links the trigger to the region it shows/hides so assistive tech can move
+ // from the button to its controlled content (disclosure pattern).
+ const contentId = useId();
+
return (
<div
ref={ref}
@@ -256,6 +261,7 @@ export function Collapsible({
type="button"
onClick={toggle}
aria-expanded={isOpen}
+ aria-controls={contentId}
{...stylex.props(
styles.trigger,
density != null && triggerDensity[density],
@@ -270,6 +276,7 @@ export function Collapsible({
</span>
</button>
<div
+ id={contentId}
{...stylex.props(
styles.content,
density != null && contentDensity[density],
diff --git a/packages/core/src/Collapsible/CollapsibleGroup.test.tsx b/packages/core/src/Collapsible/CollapsibleGroup.test.tsx
index e1885ddcf1..b4576f721e 100644
--- a/packages/core/src/Collapsible/CollapsibleGroup.test.tsx
+++ b/packages/core/src/Collapsible/CollapsibleGroup.test.tsx
@@ -77,6 +77,22 @@ describe('Collapsible', () => {
expect(screen.getByText('Hidden content')).not.toBeVisible();
});
+ it('links the trigger to its content region via aria-controls', () => {
+ render(
+ <Collapsible trigger="Details">
+ <p>Region content</p>
+ </Collapsible>,
+ );
+
+ const trigger = screen.getByRole('button', {name: /Details/});
+ const controlsId = trigger.getAttribute('aria-controls');
+ // aria-controls must be present and point at the real content region.
+ expect(controlsId).toBeTruthy();
+ const region = document.getElementById(controlsId as string);
+ expect(region).not.toBeNull();
+ expect(region).toContainElement(screen.getByText('Region content'));
+ });
+
it('respects controlled isOpen/onOpenChange', async () => {
const onOpenChange = vi.fn();
const user = userEvent.setup();