For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/en/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/en/llms-full.txt, and this page is available as Markdown at https://ifhover.github.io/leaf-ui/en/components/select.md.

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.

basic.tsx
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.

controlled.tsx
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.

sm
md
lg
control-sizes.tsx
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>
  );
}

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.

search.tsx
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.

Design studio
Current values: design
multiple.tsx
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.

Disabled
Loading
Empty options
states.tsx
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.

grouped-options.tsx
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.

Design studioProduct team
limits.tsx
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.

Default wrapping
Product design team with a longer nameFrontend developmentBackend developmentDaily operations
Single line
Product design team with a longer nameFrontend developmentBackend developmentDaily operations
single-line.tsx
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.

Design
create-option.tsx
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.

virtual-list.tsx
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.

rich-options.tsx
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>
      )}
    />
  );
}

Custom tags

Call the remove callback supplied to tagRender when a custom tag closes, so the component handles removal.

Design studioProduct team
custom-tags.tsx
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.

Match the field
Fit content, up to 320px
Fixed 300px
popup.tsx
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.

Design studio
popup-action.tsx
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.

PropertyTypeDefaultDescription
optionsreadonly (SelectOption|SelectOptionGroup)[]RequiredOptions
valuestring | readonly string[]—Controlled value; the internal uncontrolled value is used when omitted.
defaultValuestring | readonly string[]multiple ? [] : ''Initial uncontrolled value; defaults to an empty string in single mode or an empty array in multiple mode, restored on form reset.
onChange((value: string, option?: SelectOption) => void) | ((value: string[], options: SelectOption[]) => void)—Single mode returns the value and option, or an empty string and undefined when cleared; multiple mode returns value and option arrays, both empty when cleared.
multiplefalse | truefalseUse arrays for multiple values; default []
size'sm' | 'md' | 'lg''md'Control size
status'error' | 'warning'—Validation appearance
disabledbooleanfalseDisable interaction.
allowClearbooleanfalseShow a clear button
showSearchbooleanfalseAllow typing to filter options
filterOptionboolean | ((query: string, option: SelectOption) => boolean)trueCustom filtering; false supports external filtering
onSearch(query: string) => void—Search text changes
loadingbooleanfalseLoading indicator
notFoundContentReactNode—Content when no options match
maxCountnumber—Maximum selections; selected items remain removable
maxTagCountnumber | 'responsive'—Maximum visible tags; responsive collapses them to the available width.
tagWrapbooleantrueAllow selected tags to wrap; false keeps one line and collapses overflow.
allowCreatebooleanfalseAllow selecting a new option unless the query exactly matches an existing value or search text; also enables search.
onCreate(option: SelectOption) => void—Called with a newly selected option; it is kept internally, while the application updates options for persistence.
labelRender(option: SelectOption) => ReactNode—Customize the selected value.
optionRender(option: SelectOption) => ReactNode—Custom option content
tagRender(option: SelectOption, remove: () => void) => ReactNode—Customize selected tags; use remove to request removal.
openboolean—Control whether the panel is open.
defaultOpenbooleanfalseInitial open state.
onOpenChange(open: boolean) => void—Option panel open-state changes
inputReadOnlyboolean—Disable typing while retaining panel selection.
virtualbooleanMore than 100 optionsRender visible items only
listHeightnumber248List height
optionHeightnumberTheme and density dependentEstimated virtual row height, calculated from the theme and density by default; actual rows are measured.
popupWidthnumber | string'trigger'Popup width; trigger matches the trigger, auto fits content (and may be narrower), numbers specify fixed pixels; CSS lengths are also supported.
popupMaxWidthnumber | string—Optional maximum popup width; no additional limit when unset, still bounded by the viewport.
onPopupScroll(event: React.UIEvent<HTMLDivElement>) => void—Popup scroll event, useful for loading another page.
popupPlacement'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end' | 'right' | 'right-start' | 'right-end'—Placement relative to the trigger.
popupClassNamestring—Popup styling
popupStyleCSSProperties—Popup styling
popupRender(content: ReactNode) => ReactNode—Wrap or extend popup content; retain the supplied content to preserve interaction.
getPopupContainer() => Element | DocumentFragment—Return a popup container, including a ShadowRoot.
namestring—Field name in native FormData.
formstring—ID of the associated native form.
requiredbooleanfalseRequire a non-empty value; compound controls validate once.
refRef<HTMLInputElement>—DOM reference

SelectOption

An option passed through options; value identifies the option.

PropertyTypeDefaultDescription
valuestringRequiredUnique option value; empty strings are reserved.
labelReactNodeRequiredOption content, as text or a React node.
disabledbooleanfalseDisable the option.
searchLabelstring—Plain search text; defaults to a string or numeric label, otherwise value.

SelectOptionGroup API

A labeled group containing Select options.

PropertyTypeDefaultDescription
labelReactNodeRequiredVisible label or content.
optionsreadonly SelectOption[]RequiredAvailable options.