Accordion

The Accordion component allows users to toggle the visibility of sections of content. It's useful for managing complex information in a compact space.

Installation

$ cbui-cli install @crossbuildui/accordion

To get started, please make sure you have installed cbui-cli globally and authenticated your account. This will ensure you can access all the necessary features.

View documents

Import

index.tsx

import { Accordion, AccordionItem } from '@/crossbuildui/accordion';
// import Icon from 'react-native-vector-icons/MaterialCommunityIcons'; // If using custom icons for indicators or startContent

The Accordion component uses react-native-reanimated for animations. Ensure this library is installed and configured in your Expo project. If you plan to use custom icons (e.g., for indicators or startContent), you might also need a library like react-native-vector-icons.

Basic Usage

Nest AccordionItem components within an Accordion. Each AccordionItem requires a unique itemKey and a title.

index.tsx

<Accordion>
  <AccordionItem itemKey="1" title="What is CrossBuild UI?">
    CrossBuild UI is a Expo component library designed for building beautiful and consistent user interfaces across platforms.
  </AccordionItem>
  <AccordionItem itemKey="2" title="How to install components?">
    You can install components using the cbui-cli: `cbui-cli install @crossbuildui/component-name`.
  </AccordionItem>
  <AccordionItem itemKey="3" title="Is it customizable?">
    Yes, components are highly customizable through props and styling options.
  </AccordionItem>
</Accordion>

Selection Modes

Control how many items can be expanded at once using the selectionMode prop:'single' (default) allows only one item to be open, while 'multiple' allows several. Use defaultExpandedKeys to set initially open items.

index.tsx

// Single selection (default)
<Accordion selectionMode="single">
  <AccordionItem itemKey="s1" title="Section 1">Content for section 1.</AccordionItem>
  <AccordionItem itemKey="s2" title="Section 2">Content for section 2.</AccordionItem>
</Accordion>

// Multiple selection
<Accordion selectionMode="multiple" defaultExpandedKeys={["m1"]}>
  <AccordionItem itemKey="m1" title="Feature A">Details about Feature A.</AccordionItem>
  <AccordionItem itemKey="m2" title="Feature B">Details about Feature B.</AccordionItem>
  <AccordionItem itemKey="m3" title="Feature C">Details about Feature C.</AccordionItem>
</Accordion>

Variants

Accordion supports several visual variant options: 'default', 'light', 'shadow', 'bordered', and 'splitted'. These variants can be further customized using color props like accordionBackgroundColor, accordionBorderColor, accordionShadowColor, and defaultItemBorderColor.

index.tsx

<Accordion variant="light">
  <AccordionItem itemKey="l1" title="Light Variant Item 1">Content...</AccordionItem>
</Accordion>

<Accordion variant="bordered">
  <AccordionItem itemKey="b1" title="Bordered Variant Item 1">Content...</AccordionItem>
  <AccordionItem itemKey="b2" title="Bordered Variant Item 2">Content...</AccordionItem>
</Accordion>

<Accordion variant="shadow">
  <AccordionItem itemKey="sh1" title="Shadow Variant Item 1">Content...</AccordionItem>
</Accordion>

<Accordion variant="splitted">
  <AccordionItem itemKey="sp1" title="Splitted Item 1">Content...</AccordionItem>
  <AccordionItem itemKey="sp2" title="Splitted Item 2">Content...</AccordionItem>
</Accordion>

Compact Mode

Enable compact mode for a denser layout with reduced padding and smaller text sizes.

index.tsx

<Accordion compact>
  <AccordionItem itemKey="c1" title="Compact Item 1" subtitle="A small subtitle">
    This is a compact accordion item.
  </AccordionItem>
  <AccordionItem itemKey="c2" title="Compact Item 2">
    Less padding and smaller text.
  </AccordionItem>
</Accordion>

Disabled Items

Prevent specific items from being opened by passing their keys to the disabledKeys array.

index.tsx

<Accordion disabledKeys={["disabled-2"]}>
  <AccordionItem itemKey="enabled-1" title="Enabled Item">This item can be opened.</AccordionItem>
  <AccordionItem itemKey="disabled-2" title="Disabled Item">This item cannot be opened.</AccordionItem>
  <AccordionItem itemKey="enabled-3" title="Another Enabled Item">This one works too.</AccordionItem>
</Accordion>

Indicators

Customize the open/close indicator per item using the indicator prop on AccordionItem, or hide all indicators with hideIndicator on Accordion. The default indicator color can be set globally using the defaultIndicatorColor prop on Accordion. A custom indicator function receives isOpen, themeColors, and the resolved color as props.

index.tsx

// Using a function for the indicator
const CustomArrowIndicator = ({ isOpen, themeColors, color }) => (
  <Icon name={isOpen ? "chevron-up" : "chevron-down"} size={24} color={color} /> // 'color' is the resolved indicator color
);

<Accordion>
  <AccordionItem itemKey="ci1" title="Item with Custom Indicator" indicator={CustomArrowIndicator}>
    Content for item with custom indicator. The 'color' prop passed to CustomArrowIndicator is determined by 'defaultIndicatorColor' or theme.
  </AccordionItem>
  <AccordionItem itemKey="ci2" title="Item with Text Indicator" indicator="➡️">
    Content for item with text indicator.
  </AccordionItem>
</Accordion>

// Hiding indicator
<Accordion hideIndicator>
  <AccordionItem itemKey="hi1" title="No Indicator Here">
    The indicator is hidden for all items in this accordion.
  </AccordionItem>
</Accordion>

Start Content

Add icons or other elements before the title using the startContent prop on AccordionItem.

index.tsx

<Accordion>
  <AccordionItem
    itemKey="sc1"
    title="User Settings"
    startContent={<Icon name="account-cog-outline" size={24} color="purple" />}
  >
    Manage your profile and preferences.
  </AccordionItem>
  <AccordionItem
    itemKey="sc2"
    title="Notifications"
    startContent={<Icon name="bell-outline" size={24} color="orange" />}
  >
    Configure your notification settings.
  </AccordionItem>
</Accordion>

Animations

Content expansion and collapse are animated by default using fade effects. Customize animations via the motionProps prop on Accordion. You can provide duration for the default fade, or custom entering and exiting animations from react-native-reanimated. Other Animated.View props can also be passed.

index.tsx

// Using default fade animations (implicitly enabled if motionProps is present)
<Accordion motionProps={{ duration: 500 }}>
  <AccordionItem itemKey="anim1" title="Animated Item (Default)">
    This content will fade in and out.
  </AccordionItem>
</Accordion>

// To disable default animations if motionProps is used for other reasons (e.g. only style)
// or if you want to provide fully custom reanimated animations:
import Animated, { SlideInLeft, SlideOutRight } from 'react-native-reanimated';

<Accordion
  motionProps={{
    entering: SlideInLeft.duration(400),
    exiting: SlideOutRight.duration(400),
    // style: { borderWidth: 1, borderColor: 'red' } // Can also pass style to Animated.View
  }}
>
  <AccordionItem itemKey="anim2" title="Custom Animation">
    This content uses custom slide animations.
  </AccordionItem>
</Accordion>

Dividers

Control the visibility of dividers between items using the showDivider prop on Accordion. By default, dividers are shown for most variants. They are hidden by default for 'splitted' and 'bordered' variants as these items typically manage their own separation or borders. The color of the default divider can be set using defaultDividerColor.

index.tsx

<Accordion showDivider={false}>
  <AccordionItem itemKey="d1" title="No Dividers Here">Content.</AccordionItem>
  <AccordionItem itemKey="d2" title="Still No Dividers">Content.</AccordionItem>
</Accordion>

// Note: 'splitted' and 'bordered' variants hide dividers by default.
// To show them, explicitly set showDivider={true}
<Accordion variant="bordered" showDivider={true}>
 <AccordionItem itemKey="d3" title="Bordered with Divider">Content.</AccordionItem>
 <AccordionItem itemKey="d4" title="Another Bordered with Divider">Content.</AccordionItem>
</Accordion>

Props Overview

Accordion Props

PROP	TYPE	DEFAULT	DESCRIPTION
`children`	`ReactNode`	-	The `AccordionItem` components.
`variant`	`'default' \| 'light' \| 'shadow' \| 'bordered' \| 'splitted'`	`'default'`	Visual style.
`selectionMode`	`'single' \| 'multiple'`	`'single'`	Expansion behavior.
`defaultExpandedKeys`	`string[]`	`[]`	Keys of initially expanded items.
`disabledKeys`	`string[]`	`[]`	Keys of disabled items.
`hideIndicator`	`boolean`	`false`	Hide open/close indicators.
`itemClasses`	`Partial<AccordionItemClasses>`	-	Custom styles for `AccordionItem` slots, applied to all items.
`motionProps`	`object`	-	Props for item content animations (e.g., `duration`, `entering`, `exiting` from reanimated, other `Animated.View` props).
`compact`	`boolean`	`false`	Enable compact mode.
`showDivider`	`boolean`	true (false for bordered/splitted)	Show dividers. Defaults to `true`, but `false` for 'bordered'/'splitted' variants unless overridden.
`style`	`StyleProp<ViewStyle>`	-	Style for the Accordion container.
`onSelectionChange`	`(keys: Set<string>) => void`	-	Callback when expanded items change.
`defaultTitleColor`	`string`	-	Default color for item titles. Overrides theme, can be overridden by `itemClasses.title.color`.
`defaultSubtitleColor`	`string`	-	Default color for item subtitles. Overrides theme, can be overridden by `itemClasses.subtitle.color`.
`defaultIndicatorColor`	`string`	-	Default color for item indicators. Overrides theme, can be overridden by `itemClasses.indicator` styles.
`defaultItemBorderColor`	`string`	-	Border color for items in 'bordered'/'splitted' variants. Overrides theme, can be overridden by`itemClasses.base.borderColor`.
`defaultDividerColor`	`string`	-	Color for dividers. Overrides theme, can be overridden by `itemClasses.divider.backgroundColor`.
`accordionBackgroundColor`	`string`	-	Background color for Accordion container (esp. 'light', 'shadow' variants). Overrides variant defaults.
`accordionBorderColor`	`string`	-	Border color for Accordion container ('bordered' variant). Overrides variant default.
`accordionShadowColor`	`string`	-	Shadow color for Accordion container ('shadow' variant). Overrides variant default.

AccordionItem Props

PROP	TYPE	DEFAULT	DESCRIPTION
`itemKey`	`string`	-	Unique key for the item. Required
`title`	`ReactNode`	-	Title of the item. Required
`children`	`ReactNode`	-	Content to display when expanded. Required
`subtitle`	`ReactNode`	-	Optional subtitle below the title.
`startContent`	`ReactNode`	-	Content before the title.
`indicator`	`ReactNode \| (props: { isOpen: boolean; themeColors: ThemeColors; color: string }) => ReactNode`	Default Icon	Custom indicator. Can be ReactNode or a function receiving `isOpen`, `themeColors`, and resolved `color`.
`style`	`StyleProp<ViewStyle>`	-	Style for the AccordionItem's base wrapper. Overrides `itemClasses.base` for this item.
`onPress`	`PressableProps['onPress']`	-	Callback for press events on the item header.
`onFocus`	`PressableProps['onFocus']`	-	Callback for focus events.
`onBlur`	`PressableProps['onBlur']`	-	Callback for blur events.

Styling

Customize the appearance using:

style prop on Accordion for its main container.
Top-level color props on Accordion (e.g., defaultTitleColor, accordionBackgroundColor, defaultItemBorderColor) to set default colors for the accordion container and various parts of its items. These props override theme-based defaults.
itemClasses prop on Accordion to provide styles for various slots of all child AccordionItem components. Styles in itemClasses can override the global default...Color props (e.g., itemClasses.title.color overrides defaultTitleColor). Available slots:
- base: The main wrapper for an AccordionItem.
- heading: The touchable area containing the trigger.
- trigger: The interactive element that toggles the item.
- titleWrapper: Wrapper around title and subtitle.
- title: The main title text.
- subtitle: The subtitle text.
- startContent: Container for content before the title.
- indicator: The open/close indicator.
- content: The collapsible content area.
- divider: The divider line between items.
style prop on an individual AccordionItem to style its base wrapper, overriding global itemClasses.base and relevant default color props (like defaultItemBorderColor via borderColor) for that specific item.
For fine-grained control over specific elements like title or subtitle within an item, pass a custom ReactNode with inline styles to the respective prop (e.g., title={<Text style={{color: 'red'}}>Custom Title</Text>}).

index.tsx

<Accordion
  variant="splitted" // Using splitted to demonstrate item borders
  accordionBackgroundColor="whitesmoke" // Background for the Accordion container
  defaultTitleColor="darkslateblue"    // Default color for all item titles
  defaultSubtitleColor="slategray"   // Default color for all item subtitles
  defaultIndicatorColor="teal"       // Default color for all item indicators
  defaultItemBorderColor="mediumseagreen" // Border color for 'splitted' or 'bordered' items
  // defaultDividerColor would apply if dividers were shown for this variant
  style={{ paddingHorizontal: 8, marginVertical: 10 }} // Additional styles for Accordion container
  itemClasses={{
    // 'base' styles for splitted items are affected by defaultItemBorderColor
    heading: { backgroundColor: '#e0f0e0', paddingVertical: 12 },
    title: { fontWeight: '600' }, // itemClasses.title.color could override defaultTitleColor
    subtitle: { fontStyle: 'italic' },
    content: { paddingVertical: 12, backgroundColor: '#f0fff0' },
    // divider: { backgroundColor: 'red' } // Customize divider if shown
  }}
>
  <AccordionItem
    itemKey="style1"
    title="Item 1 with Custom Styling"
    subtitle="Using global and class-based styles"
    // 'style' prop on AccordionItem overrides itemClasses.base & defaultItemBorderColor for this specific item's border
    style={{ shadowColor: 'black', shadowOffset: {width: 0, height: 1}, shadowOpacity: 0.2, shadowRadius: 2, elevation: 3 }}
  >
    This item inherits default colors, gets some styles from itemClasses, and has its own shadow via the 'style' prop.
  </AccordionItem>
  <AccordionItem itemKey="style2" title="Item 2 (Styled via Accordion Props)">
    This item inherits styles from itemClasses.
  </AccordionItem>
</Accordion>

Accessibility

The Accordion component is designed with accessibility in mind:

The Accordion container has accessibilityRole="list".
Each AccordionItem header (Pressable) has accessibilityRole="button".
Item headers include accessibilityState indicating if they are expanded or disabled.
Item headers have an accessibilityLabel derived from their title.

Pagination Avatar

Installation

Import

Basic Usage

Selection Modes

Variants

Compact Mode

Disabled Items

Indicators

Start Content

Animations

Dividers

Props Overview

Accordion Props

AccordionItem Props

Styling

Accessibility

Accordion 1

Accordion 2

Accordion 3

Accordion 1Press to expand

Accordion 2Press to expand key 2

Accordion 3Press to expand

Accordion 1

Accordion 2

Accordion 3

Getting StartedComponent Documentation

Accordion ComponentExamples and Usage

Props and SlotsAPIReference