Accordion

Migration guide for Accordion from HeroUI v2 to v3

Refer to the v3 Accordion documentation for complete API reference, styling guide, and advanced examples. This guide only focuses on migrating from HeroUI v2.

Structure Changes

In v2, AccordionItem was a self-contained component that accepted props for title, subtitle, content, and other elements:

1import { Accordion, AccordionItem } from "@lenso/ui";2
3export default function App() {4  return (5    <Accordion>6      <AccordionItem7        key="1"8        title="Accordion 1"9      >10        Content here11      </AccordionItem>12      <AccordionItem13        key="2"14        title="Accordion 2"15      >16        Content here17      </AccordionItem>18    </Accordion>19  );20}

In v3, Accordion uses a compound component pattern with explicit subcomponents:

1import { Accordion } from "@lenso/ui";2
3export default function App() {4  return (5    <Accordion>6      <Accordion.Item id="1">7        <Accordion.Heading>8          <Accordion.Trigger>9            Accordion 110            <Accordion.Indicator />11          </Accordion.Trigger>12        </Accordion.Heading>13        <Accordion.Panel>14          <Accordion.Body>Content here</Accordion.Body>15        </Accordion.Panel>16      </Accordion.Item>17      <Accordion.Item id="2">18        <Accordion.Heading>19          <Accordion.Trigger>20            Accordion 221            <Accordion.Indicator />22          </Accordion.Trigger>23        </Accordion.Heading>24        <Accordion.Panel>25          <Accordion.Body>Content here</Accordion.Body>26        </Accordion.Panel>27      </Accordion.Item>28    </Accordion>29  );30}

Key Changes

1. Component Structure

v2: Single AccordionItem component with props
v3: Compound components: Accordion.Item, Accordion.Heading, Accordion.Trigger, Accordion.Panel, Accordion.Body, Accordion.Indicator

2. Prop Changes

v2 Prop	v3 Location	Notes
`selectedKeys`	`Accordion`	Renamed to `expandedKeys`; type `Iterable<Key>`
`defaultSelectedKeys`	`Accordion`	Renamed to `defaultExpandedKeys`
`onSelectionChange`	`Accordion`	Renamed to `onExpandedChange`; `(keys: Set<Key>) => void`
`selectionMode="multiple"`	`Accordion`	Use `allowsMultipleExpanded` (boolean)
`isCompact`	-	Removed (use Tailwind CSS e.g. `text-sm`, `py-2`)
`hideIndicator`	-	Omit `<Accordion.Indicator />` to hide
`disableAnimation`, `disableIndicatorAnimation`, `motionProps`	-	Removed (animations not supported / use CSS)
`showDivider`, `dividerProps`	-	Removed (add dividers manually or use `Divider`)
`keepContentMounted`	-	Removed (content always mounted in v3)
`selectionBehavior`, `disallowEmptySelection`	-	Removed (not applicable)
`itemClasses`	-	Use `className` on items
`startContent`	-	Place content in `<Accordion.Trigger>`
`title`, `subtitle`	-	Place content in `<Accordion.Trigger>`

3. Variants

v2 Variants: light, shadow, bordered, splitted
v3 Variants: default, surface

The v3 variants are simplified. To achieve similar effects to v2 variants:

v2 light → v3 default
v2 shadow → v3 surface
v2 bordered → v3 default + add border classes
v2 splitted → v3 default + add background color and spacing/margin between items

4. Item Identification

v2: React's key was used for both list reconciliation and expanded state.
v3: Use id on Accordion.Item for expanded state; keep React's key on items in lists.

Migration Examples

Controlled State

1import { useState } from "react";2import { Accordion, AccordionItem } from "@lenso/ui";3
4const [selectedKeys, setSelectedKeys] = useState(new Set(["1"]));5
6<Accordion 7  selectedKeys={selectedKeys} 8  onSelectionChange={setSelectedKeys}9>10  <AccordionItem key="1" title="Item 1">11    Content 112  </AccordionItem>13  <AccordionItem key="2" title="Item 2">14    Content 215  </AccordionItem>16</Accordion>

With Subtitle and Start Content

1import { Icon } from "@iconify/react";2
3<Accordion>4  <AccordionItem 5    key="1"6    title="Accordion 1"7    subtitle="Press to expand"8    startContent={<Icon icon="gravity-ui:box" />}9  >10    Content here11  </AccordionItem>12</Accordion>

Custom Indicator

1import { Icon } from "@iconify/react";2
3<Accordion>4  <AccordionItem 5    key="1"6    title="Item 1"7    indicator={(props) => (8      props.isOpen ? <Icon icon="mdi:minus" /> : <Icon icon="mdi:plus" />9    )}10  >11    Content12  </AccordionItem>13</Accordion>

Disabled Items and Default Expanded Keys

1<Accordion 2  defaultExpandedKeys={["1"]}3  disabledKeys={["2"]}4>5  <AccordionItem key="1" title="Item 1">6    Content 17  </AccordionItem>8  <AccordionItem key="2" title="Item 2">9    Content 210  </AccordionItem>11</Accordion>

Styling Changes

v2: `classNames` Prop

1<AccordionItem 2  classNames={{3    base: "custom-base",4    title: "custom-title",5    content: "custom-content"6  }}7/>

v3: Direct `className` Props

1<Accordion.Item className="custom-base">2  <Accordion.Heading>3    <Accordion.Trigger className="custom-title">4      Title5      <Accordion.Indicator />6    </Accordion.Trigger>7  </Accordion.Heading>8  <Accordion.Panel>9    <Accordion.Body className="custom-content">10      Content11    </Accordion.Body>12  </Accordion.Panel>13</Accordion.Item>

Component Anatomy

The v3 Accordion follows this structure:

1Accordion (Root)2  └── Accordion.Item3      ├── Accordion.Heading4      │   └── Accordion.Trigger5      │       ├── [Your content: title, subtitle, icons, etc.]6      │       └── Accordion.Indicator (optional)7      └── Accordion.Panel8          └── Accordion.Body9              └── [Your content]

Summary

Component Structure: Must use compound components instead of props
State Props: selectedKeys → expandedKeys, onSelectionChange → onExpandedChange
Multiple Selection: selectionMode="multiple" → allowsMultipleExpanded={true}
Item identity: Use id for expanded state; keep React's key for list reconciliation
Variants: Reduced from 4 to 2 variants
Removed Props: Many convenience props removed; use Tailwind CSS classes instead
Content Structure: Title, subtitle, and start content must be manually placed in Trigger
Indicator: Must be explicitly rendered; no automatic indicator