Select
Choose one or more items from a flat list. Use TreeSelect for hierarchical options.
Basic usage
Use unique, nonempty strings for option values. Give the control an associated label or an aria-label.
import { Select } from '@ifhover/leaf-ui';
const options = [
{ value: 'design', label: 'Design studio' },
{ value: 'product', label: 'Product team' },
{ value: 'engineering', label: 'Engineering team' },
{ value: 'archived', label: 'Archived project', disabled: true },
];
export function SelectBasic() {
return <Select aria-label="Choose a team" options={options} placeholder="Select a team" />;
}
Examples
Controlled value and validation
Manage the selection with value and onChange. Clearing a single selection returns "" and undefined. For controlled fields, a form reset must also reset application state.
import { Button, Form, FormField, Select, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';
export function SelectControlled() {
const [value, setValue] = useState('');
const [submitted, setSubmitted] = useState(false);
const error = submitted && !value;
return (
<Form
layout="vertical"
noValidate
onSubmit={(event) => {
event.preventDefault();
setSubmitted(true);
}}
>
<FormField label="Project visibility" error={error ? 'Select visibility' : undefined}>
<Select
name="visibility"
value={value}
onChange={setValue}
allowClear
status={error ? 'error' : undefined}
placeholder="Select an option"
options={[
{ value: 'public', label: 'Public' },
{ value: 'team', label: 'Team' },
{ value: 'private', label: 'Private' },
]}
/>
</FormField>
<Button type="submit">Submit</Button>
{submitted && value && <Text role="status">Submitted: {value}</Text>}
</Form>
);
}
Control sizes
Use size to select the control size.
import type { ControlSize } from '@ifhover/leaf-ui';
import { Button, Flex, Input, Select, Text } from '@ifhover/leaf-ui';
export function ControlSizes() {
return (
<Flex direction="column" gap="md">
{(['sm', 'md', 'lg'] as const).map((size: ControlSize) => (
<Flex key={size} align="center" gap="sm" wrap>
<Text tone="muted">{size}</Text>
<Input
style={{ flex: '1 1 120px', width: 0 }}
size={size}
aria-label={`${size} search`}
placeholder="Search projects"
/>
<Select
style={{ flex: '1 1 120px', width: 0 }}
size={size}
aria-label={`${size} status`}
defaultValue="all"
options={[
{ label: 'All statuses', value: 'all' },
{ label: 'Active', value: 'active' },
]}
/>
<Button size={size}>Search</Button>
</Flex>
))}
</Flex>
);
}
Search
Enable local filtering with showSearch. Supply searchLabel when label is a React node. For remote filtering, set filterOption={false} and update the options from onSearch.
import { Select } from '@ifhover/leaf-ui';
const options = [
{ value: 'design', label: 'Design studio' },
{ value: 'product', label: 'Product team' },
{ value: 'engineering', label: 'Engineering team' },
{ value: 'archived', label: 'Archived project', disabled: true },
];
export function SelectSearch() {
return (
<Select
aria-label="Search teams"
showSearch
allowClear
options={options}
placeholder="Type a team name"
/>
);
}
Multiple selection
Multiple selection uses a string array; clearing returns []. With name, native forms submit repeated values under that field name; read them with formData.getAll(name). With an empty search, Backspace removes the last enabled tag.
import { Flex, Select, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';
const options = [
{ value: 'design', label: 'Design studio' },
{ value: 'product', label: 'Product team' },
{ value: 'engineering', label: 'Engineering team' },
{ value: 'archived', label: 'Archived project', disabled: true },
];
export function SelectMultiple() {
const [value, setValue] = useState<string[]>(['design']);
return (
<Flex direction="column" gap="sm">
<Select
aria-label="Choose teams"
multiple
allowClear
options={options}
value={value}
onChange={setValue}
placeholder="Select teams"
/>
<Text tone="muted" role="status">
Current values: {value.join(', ') || 'None'}
</Text>
</Flex>
);
}
States
Use loading while options are being requested. Customize the empty message with notFoundContent.
import { Flex, Select, Text } from '@ifhover/leaf-ui';
const options = [
{ value: 'design', label: 'Design studio' },
{ value: 'product', label: 'Product team' },
{ value: 'engineering', label: 'Engineering team' },
{ value: 'archived', label: 'Archived project', disabled: true },
];
export function SelectStates() {
return (
<Flex direction="column" gap="md">
<Flex direction="column" gap="sm">
<Text tone="muted">Disabled</Text>
<Select
aria-label="Disabled team selection"
options={options}
defaultValue="design"
disabled
/>
</Flex>
<Flex direction="column" gap="sm">
<Text tone="muted">Loading</Text>
<Select aria-label="Loading teams" options={[]} loading placeholder="Loading" />
</Flex>
<Flex direction="column" gap="sm">
<Text tone="muted">Empty options</Text>
<Select
aria-label="No available teams"
options={[]}
notFoundContent="No teams yet"
placeholder="No teams available"
/>
</Flex>
</Flex>
);
}
Grouped options
Group labels organize options and cannot be selected. Options within a group still participate in search.
import { Select, type SelectOptionGroup } from '@ifhover/leaf-ui';
const options: SelectOptionGroup[] = [
{
label: 'Design',
options: [
{ value: 'ui', label: 'Interface design' },
{ value: 'ux', label: 'Experience design' },
],
},
{
label: 'Engineering',
options: [{ value: 'web', label: 'Frontend development' }],
},
];
export function GroupedOptions() {
return <Select aria-label="Discipline" options={options} placeholder="Select a discipline" />;
}
Selection limit
maxCount limits the number of selected values. Existing selections can still be removed at the limit.
import { Select } from '@ifhover/leaf-ui';
const options = [
{ value: 'design', label: 'Design studio' },
{ value: 'product', label: 'Product team' },
{ value: 'engineering', label: 'Engineering team' },
{ value: 'archived', label: 'Archived project', disabled: true },
];
export function SelectLimits() {
return (
<Select
aria-label="Choose up to two teams"
multiple
options={options}
defaultValue={['design', 'product']}
maxCount={2}
allowClear
placeholder="Choose up to two teams"
/>
);
}
Tag wrapping
Tags wrap by default. With tagWrap={false}, tags that do not fit collapse into +N. maxTagCount limits visible tags, not selected values; maxTagCount="responsive" also collapses tags to a single line based on the available width.
import { Flex, Select, Text } from '@ifhover/leaf-ui';
const options = [
{ value: 'design', label: 'Product design team with a longer name' },
{ value: 'web', label: 'Frontend development' },
{ value: 'server', label: 'Backend development' },
{ value: 'operations', label: 'Daily operations' },
];
const selected = options.map((option) => option.value);
export function SingleLine() {
return (
<Flex direction="column" gap="md">
<Flex direction="column" gap="sm">
<Text tone="muted">Default wrapping</Text>
<Select
aria-label="Wrapping team tags"
multiple
options={options}
defaultValue={selected}
/>
</Flex>
<Flex direction="column" gap="sm">
<Text tone="muted">Single line</Text>
<Select
aria-label="Single-line team tags"
multiple
tagWrap={false}
options={options}
defaultValue={selected}
/>
</Flex>
</Flex>
);
}
Creating options
With allowCreate, a creation candidate appears when the input has no exact match in an existing value or search label. The option is created only after choosing that candidate. Update options in onCreate to keep created options in application state.
import { Select, type SelectOption } from '@ifhover/leaf-ui';
import { useState } from 'react';
const initialOptions: SelectOption[] = [
{ value: 'design', label: 'Design' },
{ value: 'engineering', label: 'Engineering' },
];
export function CreateOption() {
const [options, setOptions] = useState(initialOptions);
const [value, setValue] = useState<string[]>(['design']);
return (
<Select
aria-label="Project tags"
multiple
allowCreate
options={options}
value={value}
onChange={setValue}
onCreate={(option) => setOptions((current) => [...current, option])}
placeholder="Select or type a new tag"
/>
);
}
Large lists
Virtual scrolling is enabled automatically above 100 options; no explicit virtual is needed. Set virtual={false} to opt out.
import { Select } from '@ifhover/leaf-ui';
const options = Array.from({ length: 5000 }, (_, index) => ({
value: String(index),
label: `Item ${index + 1}`,
}));
export function VirtualList() {
return (
<Select
aria-label="Search items"
options={options}
placeholder="Search 5000 items"
showSearch
/>
);
}
Custom option content
Use optionRender to add option details. The selected value still displays its label.
import { Select, Space, Text } from '@ifhover/leaf-ui';
const options = [
{ value: 'garden', label: 'Leaf Garden Design System' },
{ value: 'studio', label: 'Leaf Studio' },
{ value: 'notes', label: 'Leaf Notes' },
];
export function SelectRichOptions() {
return (
<Select
aria-label="Choose a project"
options={options}
placeholder="Select a project"
optionRender={(option) => (
<Space direction="vertical" align="stretch" size={0}>
<Text strong>{option.label}</Text>
<Text tone="muted">{option.value}</Text>
</Space>
)}
/>
);
}
Call the remove callback supplied to tagRender when a custom tag closes, so the component handles removal.
import { Select, Tag } from '@ifhover/leaf-ui';
const options = [
{ value: 'design', label: 'Design studio' },
{ value: 'product', label: 'Product team' },
{ value: 'engineering', label: 'Engineering team' },
{ value: 'archived', label: 'Archived project', disabled: true },
];
export function CustomTags() {
return (
<Select
aria-label="Custom team tags"
multiple
defaultValue={['design', 'product']}
options={options}
placeholder="Select teams"
tagRender={(option, remove) => (
<Tag closable onClose={remove}>
{option.label}
</Tag>
)}
/>
);
}
The popup matches the field by default. popupWidth="auto" fits the content, and a number sets a fixed pixel width. Set popupMaxWidth when a maximum is needed. All modes remain bounded by the available viewport.
import { Flex, Select, Text } from '@ifhover/leaf-ui';
const options = [
{ value: 'garden', label: 'Leaf Garden Design System' },
{ value: 'studio', label: 'Leaf Studio' },
{ value: 'notes', label: 'Leaf Notes' },
];
export function SelectPopup() {
return (
<Flex direction="column" gap="md">
<Flex direction="column" gap="sm">
<Text tone="muted">Match the field</Text>
<Select aria-label="Match the field" options={options} placeholder="Select a project" />
</Flex>
<Flex direction="column" gap="sm">
<Text tone="muted">Fit content, up to 320px</Text>
<Select
aria-label="Fit content, up to 320px"
popupWidth="auto"
popupMaxWidth={320}
options={options}
placeholder="Select a project"
/>
</Flex>
<Flex direction="column" gap="sm">
<Text tone="muted">Fixed 300px</Text>
<Select
aria-label="Fixed 300px"
popupWidth={300}
options={options}
placeholder="Select a project"
/>
</Flex>
</Flex>
);
}
Controlled popup and extra actions
Control expansion with open and onOpenChange. When adding actions with popupRender, retain the supplied content rather than replacing the option list.
import { Button, Flex, Select } from '@ifhover/leaf-ui';
import { useState } from 'react';
const options = [
{ value: 'design', label: 'Design studio' },
{ value: 'product', label: 'Product team' },
{ value: 'engineering', label: 'Engineering team' },
{ value: 'archived', label: 'Archived project', disabled: true },
];
export function PopupAction() {
const [open, setOpen] = useState(false);
return (
<Flex direction="column" gap="sm">
<Select
aria-label="Choose teams and finish"
multiple
defaultValue={['design']}
open={open}
onOpenChange={setOpen}
options={options}
placeholder="Select teams"
popupRender={(content) => (
<>
{content}
<Flex justify="end">
<Button onClick={() => setOpen(false)} size="sm">
Done
</Button>
</Flex>
</>
)}
/>
<Flex>
<Button variant="outline" onClick={() => setOpen(true)}>
Open options
</Button>
</Flex>
</Flex>
);
}
API
Select API
Select component props.
Use name, required, form and uncontrolled reset behavior for forms. Other native input props and aria-* reach the input; className and style apply to the outer container. See PopupOptions for shared popup settings.
SelectOption
An option passed through options; value identifies the option.
SelectOptionGroup API
A labeled group containing Select options.