Collapsible
Create expandable sections with smooth animations and full accessibility across all platforms.
Preview
Installation
npm install @native-ui-org/primitives
pnpm add @native-ui-org/primitives
yarn add @native-ui-org/primitives
bun add @native-ui-org/primitives
Overview
Collapsible is a compound component for building expandable/collapsible content sections with proper state management and accessibility.
| Feature | Description | Platforms |
|---|---|---|
| Collapsible | Root container managing state | iOS, Android, Web |
| Trigger | Button to toggle open/closed state | iOS, Android, Web |
| Content | Animated content area | iOS, Android, Web |
Setup & Usage Guide
Collapsible provides the structure for expandable sections. Add your own styling and animations.
1. Install and Import
Install from npm:
npm install @native-ui-org/primitivesThen import from the package:
import {
Collapsible,
CollapsibleTrigger,
CollapsibleContent
} from "@native-ui-org/primitives";2. Basic Usage (Uncontrolled)
Let the component manage its own state:
<Collapsible defaultOpen={false}>
<CollapsibleTrigger>
<Text>Toggle Content</Text>
</CollapsibleTrigger>
<CollapsibleContent>
<Text>Hidden content that appears when opened</Text>
</CollapsibleContent>
</Collapsible>3. Controlled State
Manage the open/closed state yourself:
const [isOpen, setIsOpen] = useState(false);
<Collapsible open={isOpen} onOpenChange={setIsOpen}>
<CollapsibleTrigger>
<Text>{isOpen ? 'Close' : 'Open'}</Text>
</CollapsibleTrigger>
<CollapsibleContent>
<Text>Controlled content</Text>
</CollapsibleContent>
</Collapsible>4. With Custom Styling
Add styles and icons:
<Collapsible>
<CollapsibleTrigger style={styles.trigger}>
<Text>FAQ Question</Text>
<Icon name={isOpen ? "chevron-up" : "chevron-down"} />
</CollapsibleTrigger>
<CollapsibleContent style={styles.content}>
<Text>Answer to the question...</Text>
</CollapsibleContent>
</Collapsible>API Reference
Collapsible
Root container managing state and context.
| Prop | Type | Default | Description |
|---|---|---|---|
open | boolean | — | Controlled open state |
defaultOpen | boolean | false | Initial open state (uncontrolled) |
onOpenChange | (open: boolean) => void | — | Callback when state changes |
disabled | boolean | false | Disable all interactions |
asChild | boolean | false | Use Slot pattern |
CollapsibleTrigger
Button that toggles the collapsible state.
| Prop | Type | Default | Description |
|---|---|---|---|
asChild | boolean | false | Use Slot pattern |
onPress | function | — | Additional press handler |
...props | any | — | Standard Pressable props |
CollapsibleContent
Container for collapsible content.
| Prop | Type | Default | Description |
|---|---|---|---|
forceMount | boolean | false | Keep mounted when closed |
asChild | boolean | false | Use Slot pattern |
Platform Behavior
| Platform | Implementation | Characteristics |
|---|---|---|
| iOS / Android | React Native Animated API | Native 60fps animations |
| Web | CSS transitions with JS control | Hardware accelerated |
| All Platforms | Consistent API | Same props, same behavior |
Accessibility
Web:
role="button"on triggeraria-expandedreflects statearia-controlslinks trigger to content- Keyboard navigation (Space/Enter)
Mobile:
- Proper accessibility roles
- Screen reader announces state
- Works with VoiceOver and TalkBack
Version History
| Version | Notes |
|---|---|
0.1.0 | Initial release — compound component with controlled/uncontrolled state support. |
Summary: Collapsible provides the foundation for expandable content sections. Use it for FAQs, accordions, dropdown sections, or any collapsible UI pattern. Add your own animations and styling for complete control over appearance.