Accordion

Components/Lists

Interactive docs page: https://wix-pages.com/design-system-documentation/#/component/accordion

Overview

Copy

Accordion is a list of items that shows and hides content in collapsible sections.

Do

  • Use it to organize content by grouping it into collapsible sections.
  • Use it to show information on user demand only.

Don't

  • Don't use when content is crucial to read in full. Use <Card/> with section titles instead.

Feature examples

Vertical padding

Control vertical padding of accordion items with size prop:

  • large is a larger size that emphasizes a few items.
  • medium (default) is a standard size for common cases.
  • small and tiny are compact sizes that display more items in a smaller space.

Note that size prop only controls the padding of accordion items (and not their inner content).

Copy

Horizontal padding

Control horizontal padding of accordion items and their inner content with horizontalPadding prop:

  • large (default) is a standard size for common cases.
  • medium is a more compact size.
  • small and tiny are the most compact sizes used to display more content in narrow spaces.
  • none has no horizontal padding.
Copy

Skin

Control the appearance of the accordion with skin prop:

  • standard (default) is used to visually separate accordion items from their inner content.
  • light is used when both items and their inner content need to be white.
  • neutral is used to emphasize accordion items over their inner content.
Copy

Shadow

Hide the inner content shadow with hideShadow prop.

Copy

Title and subtitle

Describe accordion items using title and subtitle props.

These containers also accept any component or a composition of multiple elements.

Copy

Title size

You can control the size of the title text:

titleSize sets the header text size: small or medium (default).

Copy

Prefix icon

Add a prefix icon in front of an accordion item with icon prop.

Copy

Sections

Organize accordion items into groups using accordionSectionItemBuilder.

Copy

Show/hide button

Define the show/hide action at the end of accordion item with buttonType prop. It can be:

  • Default chevron icon.
  • textButton.
  • button.
  • or a custom control (node).

Provide the labels for these actions, such as 'Show' and 'Hide' with expandLabel and collapseLabel props.

Copy

Initially open

By default, all accordion items are closed until expanded by the user.

Open one or multiple accordion items from the start with initiallyOpen prop.

Copy

Open multiple items

By default, only one accordion item can be open at a time.

Allow opening multiple items at once with multiple prop.

Copy

Disabled item

Disable an accordion item with disabled prop.

Users will not be able to expand or collapse it.

Copy

Content padding

contentPadding controls the inner spacing around an accordion item's expanded content.

  • Default: content keeps the built-in inner padding.
  • contentPadding="none": removes that inner padding so content starts at the container edge.
Copy

Developer examples

Using item builders

Accordion is composed from a list of items that share expand/collapse feature. To create them in the most efficient way, use accordionItemBuilder.

Note: presenting accordion items as plain objects is still available as a legacy pattern, but it shouldn't be used in any new projects.

Copy

Controlled

Component can be used in controlled mode by passing open and onToggle props to accordionItemBuilder.

Copy

Common use case examples

In a side panel

Accordion in a side panel allows for efficient use of space.

Allow to open only one accordion item at a time. This will minimise the cognitive load and scrolling required by the user.

Copy

In FAQs

Use accordion in FAQs or similar content-heavy sections. It improves scanning and navigation across related content sections.

Copy

Code

Copy

Props

NameTypeDefaultDescription
contentPadding"none"—Targets Accordion Item content padding. When not provided, uses default paddings.
dataHookstring—Applied as data-hook HTML attribute that can be used to create driver in testing.
hideShadowbooleanfalseHide Accordion shadow effect.
horizontalPadding"small" | "tiny" | "medium" | "large" | "none" | "xxTiny" | "xTiny"—Change horizontal padding.
itemsAccordionItemType[]—Provide items - Available items props: javascript { render?: func; title?: React.ReactNode; subtitle?: React.ReactNode; icon?: React.ReactNode; children?: React.ReactNode; expandLabel?: React.ReactNode; collapseLabel?: React.ReactNode; showLabel?: 'hover' | 'always'; buttonType?: 'textButton' | 'button' | 'node'; disabled?: boolean; onToggle?: React.MouseEventHandler<HTMLElement>; onMouseEnter?: React.MouseEventHandler<HTMLElement>; onMouseLeave?: React.MouseEventHandler<HTMLElement>; open?: boolean; initiallyOpen?: boolean; }
multiplebooleanfalseSpecifies whether multiple items can be expanded at the same time. When false, expanding an item collapses the one that's open.
onAnimationEnter() => void—Callback fired immediately after the animation is started.
onAnimationExit() => void—Callback fired immediately after the animation is ended.
refnull | string | (instance: AccordionComponent | null) => void | RefObject<AccordionComponent>—Allows getting a ref to the component instance. Once the component unmounts, React will set ref.current to null (or call the ref with null if you passed a callback ref).
size"small" | "tiny" | "medium" | "large" | "xxTiny" | "xTiny"'small'Change items size.
skin"standard" | "light" | "neutral"—Accordion skin color.
titleSize"small" | "medium"'medium'Accordion title and subtitle size.
transitionSpeed"medium" | "slow" | "fast"'medium'Change expand and collapse animation speed.

Testkit

Import the driver matching your test environment:

Copy

Driver methods

MethodDescription
getItemTitleAtGets the title by item index
getItemSubtitleAtGets the subtitle by item index
isIconExistsAtuse 'isPrefixExistsAt' instead
isPrefixExistsAtChecks whether prefix exists at item index
isSuffixExistsAtChecks whether suffix exists at item index
isItemExpandedAtChecks whether an item is expanded at index
isItemExpandedByTitleChecks whether an item is expanded by title
clickToggleButtonAtClicks toggle button at item index
clickItemAtClicks item at index
clickItemByTitleClicks item by title
getToggleButtonLabelAtGets toggle button label at item index
getTransitionSpeedGets transition speed
getSkinReturns skin
getHorizontalPaddingReturns size of horizontal padding
existsChecks whether the component found with the given data hook.
elementGets the component root element.
clickClicks on the component root element.
baseReturns UniDriver for the base element.

Changelog

  • 1.340.0 (2026-10-21) — maintenance release, no component-specific changes
  • 1.339.0 (2026-10-19) — maintenance release, no component-specific changes
  • 1.338.0 (2026-10-15) — maintenance release, no component-specific changes
  • 1.335.0 (2026-10-12) — maintenance release, no component-specific changes
  • 1.333.1 (2026-10-07) — fix: passing onToggle to an item no longer freezes it — the item now expands and collapses on click and still calls onToggle. An item becomes controlled only when both onToggle and open are passed. (#17380)
  • 1.331.0 (2026-10-01) — maintenance release, no component-specific changes
  • 1.329.0 (2026-09-24) — maintenance release, no component-specific changes
  • 1.328.0 (2026-09-22) — maintenance release, no component-specific changes
  • 1.325.0 (2026-09-17) — maintenance release, no component-specific changes
  • 1.324.0 (2026-09-14) — maintenance release, no component-specific changes
  • 1.318.0 (2026-08-28) — feat: the caret rotation and the content entrance animate on expand and collapse in Harmony (odeditor), following transitionSpeed. (#16928)
  • 1.315.0 (2026-08-20) — fix: with buttonType="node", the custom toggle icon no longer sits slightly above the vertical center of the header row. (#16850)
  • 1.313.1 (2026-08-18) — fix: suffix/prefix icons and the toggle caret now align vertically when used together. (#16827) — has visual changes
  • 1.313.1 (2026-08-18) — fix: restored the Accordion type export used for typing refs (e.g. useRef<Accordion>(null)), which was lost when the component was wrapped with withDefaultProps. (#16823)
  • 1.312.0 (2026-08-14) — fix: the light and neutral skins no longer render an opaque background in Studio 2.0 (odeditor-dark) — headers and content are transparent in every skin. (#16773) — has visual changes
  • 1.310.1 (2026-08-11) — fix: the caret icon stays visible in high contrast mode. (#16759)
  • 1.310.0 (2026-08-10) — maintenance release, no component-specific changes
  • 1.305.1 (2026-07-30) — fix: item dividers in Studio 2.0 (odeditor-dark) now use --wds-divider-fill-dark (#3A3A3B) instead of the default border color, fixing the doubled-divider look. (#16657)
  • 1.305.1 (2026-07-30) — fix: restore Studio 2.0 (odeditor-dark) horizontal paddings to the component spec — 16px for the default horizontalPadding="large" and 12px for "medium"; other themes keep their current rendering. (#16654) — has visual changes
  • 1.305.0 (2026-07-28) — fix: honor contentPadding="none" under skin light + hideShadow (#16640) — has visual changes
  • 1.305.0 (2026-07-28) — fix: caret rotation leaking into nested accordions (#16645) — has visual changes
  • 1.304.0 (2026-07-24) — feat: migrate to semantic classes + add expand/collapse animations (#16589)
  • 1.303.0 (2026-07-23) — fix: titleSize leaking into nested accordions (#16612) — has visual changes
  • 1.299.0 (2026-07-17) — maintenance release, no component-specific changes
  • 1.298.0 (2026-07-14) — breaking: visual changes for Harmony and Studio themes (#16508) — has visual changes
  • 1.294.0 (2026-07-02) — maintenance release, no component-specific changes
  • 1.292.0 (2026-06-22) — maintenance release, no component-specific changes
  • 1.291.0 (2026-06-19) — maintenance release, no component-specific changes
  • 1.289.0 (2026-06-17) — maintenance release, no component-specific changes
  • 1.280.0 (2026-05-19) — feat: add xTiny and xxTiny horizontal and vertical padding values (#16272) — has visual changes
  • 1.277.0 (2026-05-07) — maintenance release, no component-specific changes
  • 1.273.0 (2026-04-30) — maintenance release, no component-specific changes
  • 1.271.0 (2026-04-22) — maintenance release, no component-specific changes
  • 1.269.0 (2026-04-15) — maintenance release, no component-specific changes
  • 1.266.0 (2026-04-07) — maintenance release, no component-specific changes
  • 1.260.0 (2026-03-17) — maintenance release, no component-specific changes
  • 1.247.2 (2026-01-21) — maintenance release, no component-specific changes
  • 1.242.0 (2025-12-19) — maintenance release, no component-specific changes
  • 1.241.0 (2025-12-17) — maintenance release, no component-specific changes
  • 1.229.0 (2025-11-18) — feat: new isItemExpandedByTitle testkit method (#15521)
  • 1.228.0 (2025-11-18) — feat: new clickItemByTitle testkit method (#15505)
  • 1.218.0 (2025-09-09) — breaking: adjust fill colors & border radius (#15292)
  • 1.212.0 (2025-08-11) — maintenance release, no component-specific changes
  • 1.205.0 (2025-07-15) — maintenance release, no component-specific changes
  • 1.201.0 (2025-06-23) — maintenance release, no component-specific changes
  • 1.188.0 (2025-05-12) — feat: add titleSize prop (#14757)
  • 1.181.0 (2025-04-18) — maintenance release, no component-specific changes
  • 1.172.1 (2025-03-21) — maintenance release, no component-specific changes
  • 1.169.0 (2025-03-10) — maintenance release, no component-specific changes
  • 1.138.1 (2024-10-30) — maintenance release, no component-specific changes
  • 1.119.0 (2024-07-31) — maintenance release, no component-specific changes
  • 1.118.0 (2024-07-30) — fix: hover moved into CSS (#13987)
  • 1.115.0 (2024-07-17) — maintenance release, no component-specific changes
  • 1.102.0 (2024-04-16) — maintenance release, no component-specific changes
  • 1.101.0 (2024-04-12) — breaking: tokenized (#13571)
  • 1.93.1 (2024-02-12) — fix: added missing container for toggle button node (#13298)
  • 1.93.0 (2024-02-08) — maintenance release, no component-specific changes
  • 1.92.1 (2024-02-05) — maintenance release, no component-specific changes

Last updated: 22 October 2026

Did this help?