Accordion

Accordion display a list of high-level options that can expand/collapse to reveal more information.

Storybook @nextui-org/accordion Source Styles source

Installation

nextui add accordion

No need to install this package if @nextui-org/react is already installed globally.

Import

NextUI exports 2 accordion-related components:

Accordion: The main component to display a list of accordion items.
AccordionItem: The item component to display a single accordion item.

Usage

With Subtitle

Expand multiple items

If you set selectionMode to multiple, then the Accordion will allow multiple items to be expanded at the same time.

Compact

If you set isCompact to true, the Accordion will be displayed in a compact style.

Variants

Accordion has 4 variants: light, shadow, bordered and splitted.

Light variant

Shadow variant

Bordered variant

Splitted variant

Default expanded keys

If you want to expand some items by default, you can set the defaultExpandedKeys property to an array of keys.

Disabled keys

If you want to disable some items, you can set the disabledKeys property to an array of keys.

Start content

If you want to display some content before the accordion items, you can set the startContent property.

Custom Indicator

Accordion items have a property called indicator. You can use it to customize the open/close indicator.

The indicator can be also a function, which receives the isOpen, isDisabled and the default indicator as parameters.

Custom Motion

Accordion offers a motionProps property to customize the enter / exit animation.

Learn more about Framer motion variants here.

Controlled

Accordion is a controlled component, which means you need to control the selectedKeys property by yourself.

Accordion Item Slots

base: The accordion item wrapper.
heading: The accordion item heading. It contains the indicator and the title.
trigger: The button that open/close the accordion item.
titleWrapper: The wrapper of the title and subtitle.
title: The accordion item title.
subtitle: The accordion item subtitle.
startContent: The content before the accordion item.
indicator: The element that indicates the open/close state of the accordion item.
content: The accordion item content.

Custom Accordion Styles

You can customize the accordion and accordion items styles by using any of the following properties:

className: The class name of the accordion. Modify the accordion wrapper styles.(Accordion)
itemClasses: The class names of the accordion items. Modify all accordion items styles at once. (Accordion)
classNames: The class names of the accordion items. Modify each accordion item styles separately. (AccordionItem)

Here's an example of how to customize the accordion styles:

Data Attributes

AccordionItem has the following attributes on the base element:

data-open: Whether the accordion item is open.
data-disabled: When the accordion item is disabled.
data-hover: When the accordion item is being hovered. Based on useHover.
data-focus: When the accordion item is being focused. Based on useFocusRing.
data-focus-visible: When the accordion item is being focused with the keyboard. Based on useFocusRing.
data-disabled: When the accordion item is disabled. Based on isDisabled prop.
data-pressed: When the accordion item is pressed. Based on usePress.

Accessibility

Keyboard event support for Space, Enter, Arrow Up, Arrow Down and Home / End keys.
Keyboard focus management and cross browser normalization.
aria-expanded attribute for the accordion item.
aria-disabled attribute for the accordion item.
aria-controls attribute for the accordion item.

API

Accordion Props

Attribute	Type	Description	Default
children	`ReactNode` \| `ReactNode[]`	The contents of the collection. Usually the array of `AccordionItem`
variant	`light` \| `shadow` \| `bordered` \| `splitted`	The accordion appearance style.	`light`
selectionMode	`none` \| `single` \| `multiple`	The type of selection that is allowed in the collection.
selectionBehavior	`toggle` \| `replace`	The accordion selection behavior.	`toggle`
isCompact	`boolean`	Whether all Accordion items should be smaller.	`false`
isDisabled	`boolean`	Whether the Accordion items are disabled.
showDivider	`boolean`	Whether to display a divider at the bottom of the each accordion item.	`true`
dividerProps	DividerProps	The divider component props.	-
hideIndicator	`boolean`	Whether the Accordion items indicator is hidden.
disableAnimation	`boolean`	Whether the Accordion items open/close animation is disabled.
disableIndicatorAnimation	`boolean`	Whether the Accordion items indicator animation is disabled.
disallowEmptySelection	`boolean`	Whether the collection allows empty selection.
keepContentMounted	`boolean`	Whether the Accordion items content should be always mounted.	`false`
fullWidth	`boolean`	Whether the accordion should take up the full width of its parent container.	`true`
motionProps	`MotionProps`	The motion properties of the Accordion.
disabledKeys	`React.Key[]`	The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.
itemClasses	Classnames	The accordion items classNames.
selectedKeys	`all` \| `React.Key[]`	The currently selected keys in the collection (controlled).
defaultSelectedKeys	`all` \| `React.Key[]`	The initial selected keys in the collection (uncontrolled).
disabledKeys	`React.Key[]`	The currently disabled keys in the collection (controlled).

Accordion Events

Attribute	Type	Description
onSelectionChange	`(keys: "all" ｜ Set<React.Key>) => any`	Handler that is called when the selection changes.

Accordion Item Props

Attribute	Type	Description	Default
children	`ReactNode` \| `string`	The content of the component.
title	`ReactNode` \| `string`	The accordion item title.
subtitle	`ReactNode` \| `string`	The accordion item subtitle.
indicator	IndicatorProps	The accordion item `expanded` indicator, usually an arrow icon.
startContent	`ReactNode`	The accordion item start content, usually an icon or avatar.
motionProps	MotionProps	The props to modify the framer motion animation. Use the `variants` API to create your own animation.
isCompact	`boolean`	Whether the AccordionItem is compact.	`false`
isDisabled	`boolean`	The current disabled status.	`false`
keepContentMounted	`boolean`	Whether the AccordionItem content is kept mounted when closed.	`false`
hideIndicator	`boolean`	Whether the AccordionItem indicator is hidden.	`false`
disableAnimation	`boolean`	Whether the AccordionItem animation is disabled.	`false`
disableIndicatorAnimation	`boolean`	Whether the AccordionItem indicator animation is disabled.	`false`
HeadingComponent	`React.ElementType`	Customizable heading tag for Web accessibility. Use headings to describe content and use them consistently and semantically.	`h2`
classNames	Classnames	Allows to set custom class names for the accordion item slots.	-

Accordion Item Events

Attribute	Type	Description
onFocus	`(e: FocusEvent) => void`	Handler that is called when the element receives focus.
onBlur	`(e: FocusEvent) => void`	Handler that is called when the element loses focus.
onFocusChange	`(isFocused: boolean) => void`	Handler that is called when the element's focus status changes.
onKeyDown	`(e: KeyboardEvent) => void`	Handler that is called when a key is pressed.
onKeyUp	`(e: KeyboardEvent) => void`	Handler that is called when a key is released.
onPress	`(e: PressEvent) => void`	Handler called when the press is released over the target.
onPressStart	`(e: PressEvent) => void`	Handler called when a press interaction starts.
onPressEnd	`(e: PressEvent) => void`	Handler called when a press interaction ends, either over the target or when the pointer leaves the target.
onPressChange	`(isPressed: boolean) => void`	Handler called when the press state changes.
onPressUp	`(e: PressEvent) => void`	Handler called when a press is released over the target, regardless of whether it started on the target or not.
onClick	`MouseEventHandler`	The native button click event handler (Deprecated) use onPress instead.

Types

Accordion Item Indicator Props

export type AccordionItemIndicatorProps = {
  /**
   * The current indicator, usually an arrow icon.
   */
  indicator?: ReactNode;
  /**
   * The current open status.
   */
  isOpen?: boolean;
  /**
   * The current disabled status.
   * @default false
   */
  isDisabled?: boolean;
};

type indicator?: ReactNode | ((props: AccordionItemIndicatorProps) => ReactNode) | null;

Accordion Item classNames

export type AccordionItemClassnames = {
  base?: string;
  heading?: string;
  trigger?: string;
  titleWrapper?: string;
  title?: string;
  subtitle?: string;
  startContent?: string;
  indicator?: string;
  content?: string;
};

Motion Props

export type MotionProps = {
  /**
   * If `true`, the opacity of the content will be animated
   * @default true
   */
  animateOpacity?: boolean;
  /**
   * The height you want the content in its collapsed state.
   * @default 0
   */
  startingHeight?: number;
  /**
   * The height you want the content in its expanded state.
   * @default "auto"
   */
  endingHeight?: number | string;
  /**
   * The y-axis offset you want the content in its collapsed state.
   * @default 10
   */
  startingY?: number;
  /**
   * The y-axis offset you want the content in its expanded state.
   * @default 0
   */
  endingY?: number;
} & HTMLMotionProps;