Collapsible
A headless collapsible component that manages the visibility of content sections with full accessibility support.
Live Demo
This demo uses an icon trigger to reveal a simple stack of content rows.
<Collapsible.Root className="collapsible-demo-container"> <Collapsible.Trigger className="collapsible-trigger"> <svg className="collapsible-trigger-icon" xmlns="http://www.w3.org/2000/svg" width="17" height="17" viewBox="0 0 17 17" fill="none" > <path d="M8.33312 1.38867C4.49978 1.38867 1.38867 4.49978 1.38867 8.33312C1.38867 12.1665 4.49978 15.2776 8.33312 15.2776C12.1665 15.2776 15.2776 12.1665 15.2776 8.33312C15.2776 4.49978 12.1665 1.38867 8.33312 1.38867ZM11.1109 9.02756H9.02756V11.1109C9.02756 11.4928 8.71506 11.8053 8.33312 11.8053C7.95117 11.8053 7.63867 11.4928 7.63867 11.1109V9.02756H5.55534C5.17339 9.02756 4.86089 8.71506 4.86089 8.33312C4.86089 7.95117 5.17339 7.63867 5.55534 7.63867H7.63867V5.55534C7.63867 5.17339 7.95117 4.86089 8.33312 4.86089C8.71506 4.86089 9.02756 5.17339 9.02756 5.55534V7.63867H11.1109C11.4928 7.63867 11.8053 7.95117 11.8053 8.33312C11.8053 8.71506 11.4928 9.02756 11.1109 9.02756Z" /> </svg> </Collapsible.Trigger> <Collapsible.Content className="collapsible-content"> <div className="collapsible-item"></div> <div className="collapsible-item"></div> <div className="collapsible-item"></div> </Collapsible.Content> </Collapsible.Root>
Features
- Controlled and uncontrolled modes - Full control over open state or automatic management
- Flexible trigger elements - Support for button and custom elements with proper semantics
- Force mount option - Keep content mounted when closed for performance or search optimization
- Browser search integration - Content findability with
beforematchevent support - Polymorphic components - Render as any element using the
asprop
Import
import { Collapsible } from '@turkish-technology/spar';
Anatomy
The Collapsible component consists of three main parts:
Structure
<Collapsible.Root>
<Collapsible.Trigger />
<Collapsible.Content />
</Collapsible.Root>
Data Flow:
Collapsible: Provides context and state management for the collapsibleCollapsible.Trigger: Interactive element that toggles the content visibilityCollapsible.Content: Container that shows/hides based on the collapsible state
Code Examples
Basic Usage
Start with a trigger and one content region when you only need to show or hide a small section.
import { Collapsible } from '@turkish-technology/spar';
function BasicCollapsible() {
return (
<Collapsible.Root>
<Collapsible.Trigger>Toggle Content</Collapsible.Trigger>
<Collapsible.Content>
<p>This content can be toggled.</p>
</Collapsible.Content>
</Collapsible.Root>
);
}
Controlled State
Use controlled state when another part of the interface needs to open or close the collapsible programmatically.
import { Collapsible } from '@turkish-technology/spar';
import { useState } from 'react';
function ControlledCollapsible() {
const [isOpen, setIsOpen] = useState(false);
return (
<Collapsible.Root open={isOpen} onOpenChange={setIsOpen}>
<Collapsible.Trigger>
{isOpen ? 'Collapse' : 'Expand'}
</Collapsible.Trigger>
<Collapsible.Content>
<div>
<h3>Controlled Content</h3>
<p>The parent component controls this state</p>
</div>
</Collapsible.Content>
</Collapsible.Root>
);
}
Default Open State
defaultOpen is useful for sections that should begin expanded without managing
state yourself.
import { Collapsible } from '@turkish-technology/spar';
function DefaultOpenCollapsible() {
return (
<Collapsible.Root defaultOpen={true}>
<Collapsible.Trigger>Toggle Content</Collapsible.Trigger>
<Collapsible.Content>
<p>This content starts expanded</p>
</Collapsible.Content>
</Collapsible.Root>
);
}
Custom Trigger Element
Render the trigger as another element when the toggle needs to match an existing heading or layout pattern.
import { Collapsible } from '@turkish-technology/spar';
function CustomTriggerCollapsible() {
return (
<Collapsible.Root>
<Collapsible.Trigger as="div">
<h3>Click this heading to expand</h3>
</Collapsible.Trigger>
<Collapsible.Content>
<p>Content revealed by custom trigger.</p>
</Collapsible.Content>
</Collapsible.Root>
);
}
Force Mount Content
Keep content mounted when collapsed if you need to preserve nested state or make hidden text discoverable.
import { Collapsible } from '@turkish-technology/spar';
function ForceMountCollapsible() {
return (
<Collapsible.Root>
<Collapsible.Trigger>Toggle (Content Always Mounted)</Collapsible.Trigger>
<Collapsible.Content forceMount={true}>
<p>This content stays in the DOM even when collapsed.</p>
<p>
Useful for maintaining component state or enabling browser search.
</p>
</Collapsible.Content>
</Collapsible.Root>
);
}
Disabled State
Disable the root when the section should stay visible or hidden without allowing user interaction.
import { Collapsible } from '@turkish-technology/spar';
function DisabledCollapsible() {
return (
<Collapsible.Root disabled={true}>
<Collapsible.Trigger>Disabled Trigger</Collapsible.Trigger>
<Collapsible.Content>
<p>This content cannot be toggled</p>
</Collapsible.Content>
</Collapsible.Root>
);
}
API Reference
Collapsible / Collapsible.Root
The root component that provides context and state management for the
collapsible. Collapsible and Collapsible.Root are the same component - the
difference is only import/notation style.
Props
| Name | Type | Default | Description |
|---|---|---|---|
as? | React.ElementType | "div" | Polymorphic component type |
id? | string | - | Custom base ID for ARIA relationships. Auto-generated if not provided. |
open? | boolean | - | Controlled open state |
defaultOpen? | boolean | false | Default open state for uncontrolled usage |
onOpenChange? | (open: boolean) => void | - | Callback fired when open state changes |
disabled? | boolean | false | Whether the collapsible is disabled |
triggerId? | string | - | Unique identifier for the trigger element |
contentId? | string | - | Unique identifier for the content element |
children? | React.ReactNode | - | Child components |
Events
| Name | Parameters | Description | When Triggered |
|---|---|---|---|
onOpenChange | (open: boolean) | Open state changes | User interaction or programmatic change |
HTML Attributes
| Attribute | Value | Purpose |
|---|---|---|
data-state | "open" | "closed" | Indicates current state |
data-disabled | "" (when disabled) | Indicates disabled state |
Collapsible.Trigger
Interactive element that toggles the content visibility with full accessibility
support. Extends all Button component props including polymorphic rendering
via the as prop.
Props
| Name | Type | Default | Description |
|---|---|---|---|
as? | React.ElementType | "button" | Element type for polymorphic rendering |
children? | React.ReactNode | ((state: CollapsibleTriggerRenderProps) => React.ReactNode) | - | Trigger content or render props function |
disabled? | boolean | false | Whether trigger is disabled |
isLoading? | boolean | false | Loading state with screen reader support |
isPressed? | boolean | undefined | Toggle state - creates a toggle button when defined |
onPressedChange? | (pressed: boolean) => void | undefined | Callback fired when toggle state changes |
...props | ButtonProps | - | All standard Button component attributes |
Render Props (CollapsibleTriggerRenderProps)
| Property | Type | Description |
|---|---|---|
isOpen | boolean | Whether the collapsible content is currently visible |
disabled | boolean | Whether the trigger is disabled |
open | () => void | Function to programmatically open the collapsible |
close | () => void | Function to programmatically close the collapsible |
toggle | () => void | Function to programmatically toggle the collapsible |
Events
| Name | Parameters | Description | When Triggered |
|---|---|---|---|
onClick | (event: React.MouseEvent) | Trigger clicked | Mouse click interaction |
HTML Attributes
| Attribute | Value | Purpose |
|---|---|---|
disabled | boolean | Native disabled attribute (button elements) |
aria-expanded | boolean | Indicates whether the content is expanded |
aria-controls | string | References the ID of the content element |
data-state | "open" | "closed" | Indicates current state |
Collapsible.Content
Container that shows/hides based on the collapsible state with advanced features.
Props
| Name | Type | Default | Description |
|---|---|---|---|
as? | React.ElementType | "div" | Element type for polymorphic rendering |
forceMount? | boolean | false | Force content to remain mounted when closed |
children? | React.ReactNode | - | Content to be shown/hidden |
onBeforeMatch? | (event: Event) => void | - | Callback fired when content is found via browser search |
Events
| Name | Parameters | Description | When Triggered |
|---|---|---|---|
onBeforeMatch | (event: Event) | Content found via browser search | Browser's "find on page" feature locates content |
HTML Attributes
| Attribute | Value | Purpose |
|---|---|---|
hidden | true | "until-found" | Controls visibility and findability |
data-state | "open" | "closed" | Indicates current state |
data-disabled | "" (when disabled) | Indicates disabled state |
Keyboard Interactions
| Key | Action | Context | Notes |
|---|---|---|---|
Tab | Navigate to trigger | Always | Moves focus to the trigger element |
Shift + Tab | Navigate away from trigger | Always | Moves focus to previous focusable element |
Enter | Toggle content | Trigger focused | Activates the trigger to show/hide content |
Space | Toggle content | Trigger focused | Alternative activation method for trigger |