Skip to content

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

TypeScript

feat(collapsible): add isDisabled to disable a single item (#4139)

Cindy Zhang879b6a7b35ff
diff --git a/.changeset/collapsible-disabled.md b/.changeset/collapsible-disabled.md
new file mode 100644
index 0000000000..d10e00dd81
--- /dev/null
+++ b/.changeset/collapsible-disabled.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] Collapsible: add an `isDisabled` prop to disable a single item. A disabled item's trigger can't be toggled and is dimmed; following the system-wide disabled convention it uses `aria-disabled` (not the native `disabled` attribute) and drops out of the tab order, staying perceivable to assistive tech. Disabling doesn't collapse an already-open item. Works standalone and inside CollapsibleGroup.
+@cixzhang
diff --git a/apps/storybook/stories/Collapsible.stories.tsx b/apps/storybook/stories/Collapsible.stories.tsx
index 03ceed35fb..1242693446 100644
--- a/apps/storybook/stories/Collapsible.stories.tsx
+++ b/apps/storybook/stories/Collapsible.stories.tsx
@@ -180,6 +180,34 @@ export const StandaloneCollapsible: Story = {
),
};
+export const Disabled: Story = {
+ name: 'Disabled item',
+ render: () => (
+ <VStack gap={2}>
+ <Card>
+ <Collapsible trigger="Enabled — click to toggle">
+ <p {...stylex.props(styles.text)}>This section can be toggled.</p>
+ </Collapsible>
+ </Card>
+ <Card>
+ <Collapsible trigger="Disabled — can't be toggled" isDisabled>
+ <p {...stylex.props(styles.text)}>
+ The trigger is non-interactive and dimmed.
+ </p>
+ </Collapsible>
+ </Card>
+ <Card>
+ <Collapsible trigger="Disabled but open" isDisabled defaultIsOpen>
+ <p {...stylex.props(styles.text)}>
+ Disabling doesn't collapse an already-open item; the content stays
+ visible.
+ </p>
+ </Collapsible>
+ </Card>
+ </VStack>
+ ),
+};
+
export const WithoutCard: Story = {
name: 'Without Card (standalone)',
render: () => (
diff --git a/packages/core/src/Collapsible/Collapsible.doc.mjs b/packages/core/src/Collapsible/Collapsible.doc.mjs
index 20362dae55..caf74dd6f5 100644
--- a/packages/core/src/Collapsible/Collapsible.doc.mjs
+++ b/packages/core/src/Collapsible/Collapsible.doc.mjs
@@ -54,6 +54,12 @@ export const docs = {
type: 'boolean',
description: 'Controlled open state.',
},
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: "Disable the item so its trigger can't be toggled (dimmed, aria-disabled, and out of the tab order). Doesn't collapse an already-open item.",
+ default: 'false',
+ },
{
name: 'onOpenChange',
type: '(isOpen: boolean) => void',
diff --git a/packages/core/src/Collapsible/Collapsible.test.tsx b/packages/core/src/Collapsible/Collapsible.test.tsx
index 2b9acd3147..e833a74092 100644
--- a/packages/core/src/Collapsible/Collapsible.test.tsx
+++ b/packages/core/src/Collapsible/Collapsible.test.tsx
@@ -246,6 +246,80 @@ describe('Collapsible', () => {
});
});
+ describe('disabled state', () => {
+ it('marks the trigger aria-disabled and drops it from the tab order', () => {
+ render(
+ <Collapsible trigger="T" isDisabled>
+ Body
+ </Collapsible>,
+ );
+ const button = screen.getByRole('button');
+ expect(button).toHaveAttribute('aria-disabled', 'true');
+ expect(button).toHaveAttribute('tabindex', '-1');
+ // Never the native disabled attribute — it stays focusable/perceivable.
+ expect(button).not.toBeDisabled();
+ });
+
+ it('is enabled by default (no aria-disabled, stays in tab order)', () => {
+ render(<Collapsible trigger="T">Body</Collapsible>);
+ const button = screen.getByRole('button');
+ expect(button).not.toHaveAttribute('aria-disabled');
+ expect(button).not.toHaveAttribute('tabindex', '-1');
+ });
+
+ it('does not toggle when the trigger is clicked while disabled', async () => {
+ const user = userEvent.setup();
+ render(
+ <Collapsible trigger="T" isDisabled defaultIsOpen>
+ Body
+ </Collapsible>,
+ );
+ const button = screen.getByRole('button');
+ expect(button).toHaveAttribute('aria-expanded', 'true');
+ await user.click(button);
+ expect(button).toHaveAttribute('aria-expanded', 'true');
+ });
+
+ it('does not fire onOpenChange while disabled', async () => {
+ const user = userEvent.setup();
+ const onOpenChange = vi.fn();
+ render(
+ <Collapsible trigger="T" isDisabled onOpenChange={onOpenChange}>
+ Body
+ </Collapsible>,
+ );
+ await user.click(screen.getByRole('button'));
+ expect(onOpenChange).not.toHaveBeenCalled();
+ });
+
+ it('does not collapse an already-open item — content stays visible', () => {
+ render(
+ <Collapsible trigger="T" isDisabled defaultIsOpen>
+ Body
+ </Collapsible>,
+ );
+ const content = contentFor(screen.getByRole('button'));
+ expect(content).not.toHaveStyle({display: 'none'});
+ });
+
+ it('does not toggle its group item when disabled', async () => {
+ const user = userEvent.setup();
+ render(
+ <CollapsibleGroup type="single">
+ <Collapsible trigger="A" value="a" isDisabled>
+ Body A
+ </Collapsible>
+ <Collapsible trigger="B" value="b">
+ Body B
+ </Collapsible>
+ </CollapsibleGroup>,
+ );
+ const triggerA = screen.getByRole('button', {name: /A/});
+ await user.click(triggerA);
+ expect(triggerA).toHaveAttribute('aria-expanded', 'false');
+ });
+ });
+
describe('prop forwarding', () => {
it('forwards a ref to the root element', () => {
const ref = vi.fn();
diff --git a/packages/core/src/Collapsible/Collapsible.tsx b/packages/core/src/Collapsible/Collapsible.tsx
index 8b9d863631..ef03a7c0c8 100644
--- a/packages/core/src/Collapsible/Collapsible.tsx
+++ b/packages/core/src/Collapsible/Collapsible.tsx
@@ -82,6 +82,13 @@ const styles = stylex.create({
textBoxEdge: 'cap alphabetic',
textBoxTrim: 'trim-both',
},
+ // Disabled trigger — non-interactive, dimmed. Native `disabled` on the
+ // button blocks click + keyboard activation; these styles restore the
+ // visual affordance that `all: unset` wipes.
+ triggerDisabled: {
+ cursor: 'not-allowed',
+ opacity: 0.5,
+ },
// Chevron indicator
chevron: {
display: 'inline-flex',
@@ -176,6 +183,17 @@ export interface CollapsibleProps extends BaseProps {
*/
isOpen?: boolean;
+ /**
+ * Whether the collapsible is disabled. A disabled item can't be toggled —
+ * its trigger is non-interactive and dimmed. Following the system-wide
+ * disabled convention, the trigger uses `aria-disabled` (not the native
+ * `disabled` attribute) and drops out of the tab order, staying perceivable
+ * to assistive tech. The content stays in whatever open state it was;
+ * disabling doesn't collapse an already-open item.
+ * @default false
+ */
+ isDisabled?: boolean;
+
/**
* Callback when the open state changes.
*/
@@ -235,6 +253,7 @@ export function Collapsible({
children,
defaultIsOpen,
isOpen: controlledIsOpen,
+ isDisabled = false,
onOpenChange,
value,
ref,
@@ -254,6 +273,17 @@ export function Collapsible({
value,
});
+ // Activation is blocked by this guard rather than the native `disabled`
+ // attribute, so the trigger keeps `aria-disabled` semantics and stays
+ // discoverable. A native `disabled` button would silently swallow events
+ // (e.g. a wrapping tooltip's hover) — the system-wide disabled convention.
+ const handleToggle = () => {
+ if (isDisabled) {
+ return;
+ }
+ toggle();
+ };
+
const presentation = use(CollapsibleGroupPresentationContext);
const isDivided = presentation?.hasDividers ?? false;
const density = presentation?.density ?? null;
@@ -278,12 +308,20 @@ export function Collapsible({
{...props}>
<button
type="button"
- onClick={toggle}
+ onClick={handleToggle}
+ aria-disabled={isDisabled || undefined}
aria-expanded={isOpen}
aria-controls={contentId}
+ // A disabled trigger drops out of the tab order so it isn't a silently
+ // dead tab stop; activation stays blocked by the handleToggle guard,
+ // and aria-disabled keeps the state perceivable to assistive tech —
+ // the system-wide disabled convention (never native `disabled`, which
+ // would swallow events like a wrapping tooltip's hover).
+ tabIndex={isDisabled ? -1 : undefined}
{...stylex.props(
styles.trigger,
density != null && triggerDensity[density],
+ isDisabled && styles.triggerDisabled,
)}>
<span {...stylex.props(styles.triggerLabel)}>{trigger}</span>
<span