Skip to main content

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.

JavaScript
<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 beforematch event support
  • Polymorphic components - Render as any element using the as prop

Import​

import { Collapsible } from '@turkish-technology/spar';

Anatomy​

The Collapsible component consists of three main parts:

Parts
RootContext and state provider
TriggerToggle button
ContentCollapsible content container

Structure​

<Collapsible.Root>
<Collapsible.Trigger />
<Collapsible.Content />
</Collapsible.Root>

Data Flow:

  • Collapsible: Provides context and state management for the collapsible
  • Collapsible.Trigger: Interactive element that toggles the content visibility
  • Collapsible.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

NameTypeDefaultDescription
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?booleanfalseDefault open state for uncontrolled usage
onOpenChange?(open: boolean) => void-Callback fired when open state changes
disabled?booleanfalseWhether 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

NameParametersDescriptionWhen Triggered
onOpenChange(open: boolean)Open state changesUser interaction or programmatic change

HTML Attributes

AttributeValuePurpose
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

NameTypeDefaultDescription
as?React.ElementType"button"Element type for polymorphic rendering
children?React.ReactNode | ((state: CollapsibleTriggerRenderProps) => React.ReactNode)-Trigger content or render props function
disabled?booleanfalseWhether trigger is disabled
isLoading?booleanfalseLoading state with screen reader support
isPressed?booleanundefinedToggle state - creates a toggle button when defined
onPressedChange?(pressed: boolean) => voidundefinedCallback fired when toggle state changes
...propsButtonProps-All standard Button component attributes

Render Props (CollapsibleTriggerRenderProps)

PropertyTypeDescription
isOpenbooleanWhether the collapsible content is currently visible
disabledbooleanWhether the trigger is disabled
open() => voidFunction to programmatically open the collapsible
close() => voidFunction to programmatically close the collapsible
toggle() => voidFunction to programmatically toggle the collapsible

Events

NameParametersDescriptionWhen Triggered
onClick(event: React.MouseEvent)Trigger clickedMouse click interaction

HTML Attributes

AttributeValuePurpose
disabledbooleanNative disabled attribute (button elements)
aria-expandedbooleanIndicates whether the content is expanded
aria-controlsstringReferences 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

NameTypeDefaultDescription
as?React.ElementType"div"Element type for polymorphic rendering
forceMount?booleanfalseForce 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

NameParametersDescriptionWhen Triggered
onBeforeMatch(event: Event)Content found via browser searchBrowser's "find on page" feature locates content

HTML Attributes

AttributeValuePurpose
hiddentrue | "until-found"Controls visibility and findability
data-state"open" | "closed"Indicates current state
data-disabled"" (when disabled)Indicates disabled state

Keyboard Interactions​

KeyActionContextNotes
TabNavigate to triggerAlwaysMoves focus to the trigger element
Shift + TabNavigate away from triggerAlwaysMoves focus to previous focusable element
EnterToggle contentTrigger focusedActivates the trigger to show/hide content
SpaceToggle contentTrigger focusedAlternative activation method for trigger