Accordion

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


Installation

npx nextui-cli@latest add accordion
The above command is for individual installation only. You may skip this step 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

AttributeTypeDescriptionDefault
childrenReactNode | ReactNode[]The contents of the collection. Usually the array of AccordionItem
variantlight | shadow | bordered | splittedThe accordion appearance style.light
selectionModenone | single | multipleThe type of selection that is allowed in the collection.
selectionBehaviortoggle | replaceThe accordion selection behavior.toggle
isCompactbooleanWhether all Accordion items should be smaller.false
isDisabledbooleanWhether the Accordion items are disabled.
showDividerbooleanWhether to display a divider at the bottom of the each accordion item.true
dividerPropsDividerPropsThe divider component props.-
hideIndicatorbooleanWhether the Accordion items indicator is hidden.
disableAnimationbooleanWhether the Accordion items open/close animation is disabled.
disableIndicatorAnimationbooleanWhether the Accordion items indicator animation is disabled.
disallowEmptySelectionbooleanWhether the collection allows empty selection.
keepContentMountedbooleanWhether the Accordion items content should be always mounted.false
fullWidthbooleanWhether the accordion should take up the full width of its parent container.true
motionPropsMotionPropsThe motion properties of the Accordion.
disabledKeysReact.Key[]The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.
itemClassesClassnamesThe accordion items classNames.
selectedKeysall | React.Key[]The currently selected keys in the collection (controlled).
defaultSelectedKeysall | React.Key[]The initial selected keys in the collection (uncontrolled).
disabledKeysReact.Key[]The currently disabled keys in the collection (controlled).

Accordion Events

AttributeTypeDescription
onSelectionChange(keys: "all" | Set<React.Key>) => anyHandler that is called when the selection changes.

Accordion Item Props

AttributeTypeDescriptionDefault
childrenReactNode | stringThe content of the component.
titleReactNode | stringThe accordion item title.
subtitleReactNode | stringThe accordion item subtitle.
indicatorIndicatorPropsThe accordion item expanded indicator, usually an arrow icon.
startContentReactNodeThe accordion item start content, usually an icon or avatar.
motionPropsMotionPropsThe props to modify the framer motion animation. Use the variants API to create your own animation.
isCompactbooleanWhether the AccordionItem is compact.false
isDisabledbooleanThe current disabled status.false
keepContentMountedbooleanWhether the AccordionItem content is kept mounted when closed.false
hideIndicatorbooleanWhether the AccordionItem indicator is hidden.false
disableAnimationbooleanWhether the AccordionItem animation is disabled.false
disableIndicatorAnimationbooleanWhether the AccordionItem indicator animation is disabled.false
HeadingComponentReact.ElementTypeCustomizable heading tag for Web accessibility. Use headings to describe content and use them consistently and semantically.h2
classNamesClassnamesAllows to set custom class names for the accordion item slots.-

Accordion Item Events

AttributeTypeDescription
onFocus(e: FocusEvent) => voidHandler that is called when the element receives focus.
onBlur(e: FocusEvent) => voidHandler that is called when the element loses focus.
onFocusChange(isFocused: boolean) => voidHandler that is called when the element's focus status changes.
onKeyDown(e: KeyboardEvent) => voidHandler that is called when a key is pressed.
onKeyUp(e: KeyboardEvent) => voidHandler that is called when a key is released.
onPress(e: PressEvent) => voidHandler called when the press is released over the target.
onPressStart(e: PressEvent) => voidHandler called when a press interaction starts.
onPressEnd(e: PressEvent) => voidHandler called when a press interaction ends, either over the target or when the pointer leaves the target.
onPressChange(isPressed: boolean) => voidHandler called when the press state changes.
onPressUp(e: PressEvent) => voidHandler called when a press is released over the target, regardless of whether it started on the target or not.
onClickMouseEventHandlerThe 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;