Dropdown

Migration guide for Dropdown from HeroUI v2 to v3

Structure Changes

In v2, Dropdown used separate components: DropdownTrigger, DropdownMenu, DropdownItem, DropdownSection:

1import { Dropdown, DropdownTrigger, DropdownMenu, DropdownItem, Button } from "@lenso/ui";2
3export default function App() {4  return (5    <Dropdown>6      <DropdownTrigger>7        <Button>Open Menu</Button>8      </DropdownTrigger>9      <DropdownMenu>10        <DropdownItem key="new">New file</DropdownItem>11        <DropdownItem key="copy">Copy link</DropdownItem>12      </DropdownMenu>13    </Dropdown>14  );15}

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

1import { Dropdown, Button, Label } from "@lenso/ui";2
3export default function App() {4  return (5    <Dropdown>6      <Button>Open Menu</Button>7      <Dropdown.Popover>8        <Dropdown.Menu>9          <Dropdown.Item id="new" textValue="New file">10            <Label>New file</Label>11          </Dropdown.Item>12          <Dropdown.Item id="copy" textValue="Copy link">13            <Label>Copy link</Label>14          </Dropdown.Item>15        </Dropdown.Menu>16      </Dropdown.Popover>17    </Dropdown>18  );19}

Key Changes

1. Component Structure

v2: Separate components: DropdownTrigger, DropdownMenu, DropdownItem, DropdownSection
v3: Compound components: Dropdown.Trigger, Dropdown.Popover, Dropdown.Menu, Dropdown.Item, Dropdown.Section

2. Component Name Changes

3. Item Identification

v2: Item content passed as children; React's key was used for both list reconciliation and item identity (selection, focus).
v3: Item content must use Label component for text. Give each item an id (for state/focus) and textValue (for accessibility when content isn't plain text). Keep React's key on items in lists.

4. Prop Changes

5. New Components

• Dropdown.Popover - Required wrapper around Dropdown.Menu
• Dropdown.ItemIndicator - For selection indicators (checkmark/dot)
• Dropdown.SubmenuTrigger - For submenu functionality
• Dropdown.SubmenuIndicator - For submenu chevron indicator

Migration Examples

With Action Handler

1<DropdownMenu onAction={(key) => alert(key)}>2  <DropdownItem key="new">New file</DropdownItem>3</DropdownMenu>

Item Content

1{/* With icon */}2<DropdownItem3  key="new"4  startContent={<AddNoteIcon />}5>6  New file7</DropdownItem>8
9{/* With description */}10<DropdownItem11  key="edit"12  description="Edit the file"13>14  Edit file15</DropdownItem>16
17{/* With shortcut */}18<DropdownItem19  key="copy"20  shortcut="⌘C"21>22  Copy23</DropdownItem>

Danger Item

1<DropdownItem2  key="delete"3  className="text-danger"4  color="danger"5>6  Delete file7</DropdownItem>

With Sections

1<DropdownMenu>2  <DropdownSection showDivider title="Actions">3    <DropdownItem key="new">New file</DropdownItem>4    <DropdownItem key="edit">Edit file</DropdownItem>5  </DropdownSection>6  <DropdownSection title="Danger zone">7    <DropdownItem key="delete" color="danger">Delete file</DropdownItem>8  </DropdownSection>9</DropdownMenu>

Selection

1import { useState } from "react";2
3{/* Single selection */}4const [singleSelected, setSingleSelected] = useState(new Set(["text"]));5<DropdownMenu6  selectedKeys={singleSelected}7  selectionMode="single"8  onSelectionChange={setSingleSelected}9>10  <DropdownItem key="text">Text</DropdownItem>11  <DropdownItem key="number">Number</DropdownItem>12</DropdownMenu>13
14{/* Multiple selection */}15const [multiSelected, setMultiSelected] = useState(new Set(["bold"]));16<DropdownMenu17  selectedKeys={multiSelected}18  selectionMode="multiple"19  onSelectionChange={setMultiSelected}20>21  <DropdownItem key="bold">Bold</DropdownItem>22  <DropdownItem key="italic">Italic</DropdownItem>23</DropdownMenu>

With Keyboard Shortcuts

1<DropdownItem key="copy" shortcut="⌘C">2  Copy3</DropdownItem>

With Submenus

1{/* v2 did not have built-in submenu support */}

Long Press Trigger

1<Dropdown>2  <DropdownTrigger>3    <Button>Long press me</Button>4  </DropdownTrigger>5  <DropdownMenu>6    <DropdownItem key="cut">Cut</DropdownItem>7    <DropdownItem key="copy">Copy</DropdownItem>8  </DropdownMenu>9</Dropdown>

Component Anatomy

The v3 Dropdown follows this structure:

1Dropdown (Root) — accepts trigger="press" | "longPress"2  ├── Dropdown.Trigger (optional, defaults to first child)3  ├── Dropdown.Popover (required wrapper)4  │   └── Dropdown.Menu5  │       ├── Dropdown.Item6  │       │   ├── Icon (optional, first child)7  │       │   ├── Label (required for text)8  │       │   ├── Description (optional)9  │       │   ├── Kbd slot="keyboard" (optional, for shortcuts)10  │       │   └── Dropdown.ItemIndicator (optional, for selection)11  │       ├── Separator (for dividers)12  │       ├── Dropdown.Section13  │       │   ├── Header (optional)14  │       │   └── Dropdown.Item15  │       └── Dropdown.SubmenuTrigger16  │           ├── Dropdown.Item17  │           │   ├── Label18  │           │   └── Dropdown.SubmenuIndicator (chevron icon)19  │           └── Dropdown.Popover20  │               └── Dropdown.Menu21  │                   └── Dropdown.Item

Summary

1. Component Structure: Must use compound components (Dropdown.Trigger, Dropdown.Popover, Dropdown.Menu, etc.)
2. Dropdown.Popover Required: Dropdown.Menu must be wrapped in Dropdown.Popover
3. Label Component: Item text must use Label component
4. Description Component: Use Description component instead of description prop
5. Kbd Component: Use Kbd with slot="keyboard" instead of the shortcut prop — the slot positions the shortcut at the end of the menu item
6. Icons as Children: Icons go as first child, not startContent prop
7. Separator Component: Use Separator instead of showDivider prop
8. ItemIndicator Component: Use Dropdown.ItemIndicator for selection indicators
9. Variant Instead of Color: Use variant="danger" instead of color="danger"
10. No Menu Variants: Dropdown.Menu no longer supports variant or color props
11. ClassNames Removed: Use className props on individual components
12. Submenu Support: Use Dropdown.SubmenuTrigger to wrap an item that opens a nested menu, and Dropdown.SubmenuIndicator inside the item for a chevron icon
13. Trigger Prop: Use trigger="longPress" on Dropdown root to open the menu on long press instead of the default press