Select

Migration guide for Select from HeroUI v2 to v3

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

Structure Changes

In v2, Select used a simple structure with props:

1import { Select, SelectItem } from "@lenso/ui";2
3export default function App() {4  return (5    <Select label="Select animal" placeholder="Choose one">6      <SelectItem key="cat">Cat</SelectItem>7      <SelectItem key="dog">Dog</SelectItem>8    </Select>9  );10}

In v3, Select requires compound components and uses ListBox for items:

1import { Select, Label, ListBox } from "@lenso/ui";2
3export default function App() {4  return (5    <Select placeholder="Choose one">6      <Label>Select animal</Label>7      <Select.Trigger>8        <Select.Value />9        <Select.Indicator />10      </Select.Trigger>11      <Select.Popover>12        <ListBox>13          <ListBox.Item id="cat" textValue="Cat">14            Cat15            <ListBox.ItemIndicator />16          </ListBox.Item>17          <ListBox.Item id="dog" textValue="Dog">18            Dog19            <ListBox.ItemIndicator />20          </ListBox.Item>21        </ListBox>22      </Select.Popover>23    </Select>24  );25}

Key Changes

1. Component Structure

v2: Simple Select with SelectItem children
v3: Compound components (Select.Trigger, Select.Value, Select.ClearButton, Select.Indicator, Select.Popover) with ListBox for items

2. Item Components

v2: SelectItem, SelectSection v3: ListBox.Item, ListBox.Section (with Header for section titles and Separator between sections)

3. Prop Changes

v2 Prop	v3 Location	Notes
`selectedKeys`	`value`	Changed from Set/array to single value or array
`onSelectionChange`	`onChange`	Renamed event handler
`defaultSelectedKeys`	`defaultValue`	Renamed prop
`label`	—	Use `Label` component
`description`	—	Use `Description` component
`errorMessage`	—	Use `FieldError` component
`variant`	`variant`	Simplified to `primary` \| `secondary` only
`color`	—	Removed (use Tailwind CSS)
`size`	—	Removed (use Tailwind CSS)
`radius`	—	Removed (use Tailwind CSS)
`classNames`	—	Use `className` props on individual components
`startContent`	—	Customize `Select.Trigger` directly
`endContent`	—	Customize `Select.Trigger` directly
`selectorIcon`	—	Customize `Select.Indicator` children
`isClearable`	`Select.ClearButton`	Built-in subcomponent; do not nest a `<button>` in `Select.Trigger`
`renderValue`	—	Use `Select.Value` render prop
`labelPlacement`	—	Labels are always outside
`isRequired`	`isRequired`	Still exists
`disabledKeys`	`disabledKeys`	Still exists
`isOpen`	`isOpen`	New: controls the open state of the popover (controlled)
`defaultOpen`	`defaultOpen`	New: sets the default open state of the popover (uncontrolled)
`onOpenChange`	`onOpenChange`	New: handler called when the open state changes
`selectionMode`	`selectionMode`	Still exists
`disableAnimation`	—	Removed (animations handled differently)
`popoverProps`, `listboxProps`, `scrollShadowProps`	—	Use props on `Select.Popover`, `ListBox`, etc. directly

Migration Examples

Selection

1import { useState } from "react";2
3{/* Single selection */}4const [singleValue, setSingleValue] = useState(new Set([]));5<Select6  selectedKeys={singleValue}7  onSelectionChange={setSingleValue}8  label="Select animal"9>10  <SelectItem key="cat">Cat</SelectItem>11  <SelectItem key="dog">Dog</SelectItem>12</Select>13
14{/* Multiple selection */}15const [multiValue, setMultiValue] = useState(new Set([]));16<Select17  selectionMode="multiple"18  selectedKeys={multiValue}19  onSelectionChange={setMultiValue}20  label="Select animals"21>22  <SelectItem key="cat">Cat</SelectItem>23  <SelectItem key="dog">Dog</SelectItem>24</Select>

Form Validation

1{/* With description */}2<Select3  label="Select animal"4  description="Choose your favorite"5  placeholder="Choose one"6>7  <SelectItem key="cat">Cat</SelectItem>8</Select>9
10{/* With validation */}11<Select12  isInvalid13  errorMessage="Please select an option"14  label="Select animal"15>16  <SelectItem key="cat">Cat</SelectItem>17</Select>

With Sections

1import { Select, SelectItem, SelectSection } from "@lenso/ui";2
3<Select label="Select animal">4  <SelectSection title="Mammals">5    <SelectItem key="cat">Cat</SelectItem>6    <SelectItem key="dog">Dog</SelectItem>7  </SelectSection>8  <SelectSection title="Birds">9    <SelectItem key="eagle">Eagle</SelectItem>10    <SelectItem key="parrot">Parrot</SelectItem>11  </SelectSection>12</Select>

Controlled Open State

1{/* v2 did not have controlled open state */}2<Select label="Select animal">3  <SelectItem key="cat">Cat</SelectItem>4  <SelectItem key="dog">Dog</SelectItem>5</Select>

Disabled Options

1import { Select, SelectItem } from "@lenso/ui";2
3<Select label="Select animal" disabledKeys={["dog"]}>4  <SelectItem key="cat">Cat</SelectItem>5  <SelectItem key="dog">Dog</SelectItem>6  <SelectItem key="parrot">Parrot</SelectItem>7</Select>

Required

1import { Select, SelectItem } from "@lenso/ui";2
3<Select isRequired label="Select animal">4  <SelectItem key="cat">Cat</SelectItem>5  <SelectItem key="dog">Dog</SelectItem>6</Select>

Custom Indicator

1<Select selectorIcon={<CustomIcon />} label="Select animal">2  <SelectItem key="cat">Cat</SelectItem>3</Select>

Component Anatomy

The v3 Select follows this structure:

1Select (Root)2  ├── Label (optional)3  ├── Select.Trigger4  │   ├── Select.Value5  │   ├── Select.ClearButton (optional)6  │   └── Select.Indicator7  ├── Description (optional)8  ├── Select.Popover9  │   └── ListBox10  │       ├── ListBox.Item11  │       │   ├── Label (optional)12  │       │   ├── Description (optional)13  │       │   └── ListBox.ItemIndicator14  │       ├── ListBox.Section (optional)15  │       │   ├── Header (section title)16  │       │   └── ListBox.Item17  │       └── Separator (optional, between sections)18  └── FieldError (optional)

Important Notes

Item Identification

v2: React's key was used for both list reconciliation and item identity for selection.
v3: Use id for state/focus and textValue for accessibility on ListBox.Item; keep React's key for list reconciliation.

Selection Value Types

v2: selectedKeys was a Set<Key> or array
v3: value is Key | null for single selection or Key[] for multiple selection

Clear Button

The isClearable prop has been removed. Use Select.ClearButton inside Select.Trigger. Do not nest a <button> in the trigger — Select.Trigger is already a button.

The clear control is a pointer affordance; the trigger also clears on Backspace or Delete for keyboard and screen reader users.

1<Select value={value} onChange={setValue}>2  <Select.Trigger>3    <Select.Value />4    <Select.ClearButton />5    <Select.Indicator />6  </Select.Trigger>7  {/* ... */}8</Select>

Summary

Component Structure: Must use compound components (Select.Trigger, Select.Value, Select.ClearButton, Select.Indicator, Select.Popover)
Item Components: SelectItem → ListBox.Item, SelectSection → ListBox.Section (use Header for section titles and Separator between sections)
Label/Description/Error: Use separate components instead of props
Selection Props: selectedKeys/onSelectionChange → value/onChange
Controlled Open State: New isOpen, defaultOpen, and onOpenChange props for controlling the popover open state
Disabled Options: disabledKeys prop still supported for disabling specific items
Required: isRequired prop still supported for marking the field as required
Styling: variant simplified to primary | secondary; color, size, radius removed - use Tailwind for more
ClassNames Removed: Use className props on individual components
Content Props Removed: startContent, endContent - customize trigger directly
Clear Button: isClearable removed - use Select.ClearButton inside Select.Trigger (do not nest a <button>)
Custom Value: Use Select.Value render prop instead of renderValue