> Leaf UI 0.17.3 · Package: @ifhover/leaf-ui · Source: c3221834f84f2f48481a2054026b713456f8e5dc
> Browser documentation: https://ifhover.github.io/leaf-ui/en/components/select.html

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

# Select

Choose one or more items from a flat list. Use [TreeSelect](https://ifhover.github.io/leaf-ui/en/components/tree-select.md) for hierarchical options.


## Basic usage

[](#)
Use unique, nonempty strings for option values. Give the control an associated label or an `aria-label`.


basic.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/select/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" />;
}
```

Expand code


## 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.


Project visibility

Submit

controlled.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/select/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>
  );
}
```

Expand code

### Control sizes

Use `size` to select the control size.


smSearch

mdSearch

lgSearch

control-sizes.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/guide/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>
  );
}
```

Expand code

### 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`.


search.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/select/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"
    />
  );
}
```

Expand code

### 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

Copy code

```tsx lineNumbers file="../../../src/examples/en/select/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>
  );
}
```

Expand code

### States

Use `loading` while options are being requested. Customize the empty message with `notFoundContent`.


Disabled

Loading

Empty options

states.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/select/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>
  );
}
```

Expand code

### Grouped options

Group labels organize options and cannot be selected. Options within a group still participate in search.


grouped-options.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/select/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" />;
}
```

Expand code

### Selection limit

`maxCount` limits the number of selected values. Existing selections can still be removed at the limit.


Design studioProduct team

limits.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/select/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"
    />
  );
}
```

Expand code

### 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+4

single-line.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/select/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>
  );
}
```

Expand code

### 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

Copy code

```tsx lineNumbers file="../../../src/examples/en/select/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"
    />
  );
}
```

Expand code

### Large lists

Virtual scrolling is enabled automatically above 100 options; no explicit `virtual` is needed. Set `virtual={false}` to opt out.


virtual-list.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/select/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
    />
  );
}
```

Expand code

### Custom option content

Use `optionRender` to add option details. The selected value still displays its `label`.


rich-options.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/select/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>
      )}
    />
  );
}
```

Expand code

### 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

Copy code

```tsx lineNumbers file="../../../src/examples/en/select/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>
      )}
    />
  );
}
```

Expand code

### Popup width

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

Copy code

```tsx lineNumbers file="../../../src/examples/en/select/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>
  );
}
```

Expand code

### 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

Open options

popup-action.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/select/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>
  );
}
```

Expand code


## API

### Select API

Select component props.

Use `name`, `required`, `form` and uncontrolled reset behavior for [forms](https://ifhover.github.io/leaf-ui/en/components/form.md). Other native input props and `aria-*` reach the input; `className` and `style` apply to the outer container. See [PopupOptions](https://ifhover.github.io/leaf-ui/en/api/popup-options.md) for shared popup settings.

| Property            | Type                                                                                                                                                                 | Default                     | Description                                                                                                                                                      |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `options`           | `readonly (`[`SelectOption`](#selectoption)`\|`[`SelectOptionGroup`](#selectoptiongroup-api)`)[]`                                                                    | Required                    | Options                                                                                                                                                          |
| `value`             | `string \| readonly string[]`                                                                                                                                        | —                           | Controlled value; the internal uncontrolled value is used when omitted.                                                                                          |
| `defaultValue`      | `string \| 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`](#selectoption)`) => void) \| ((value: string[], options: `[`SelectOption`](#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. |
| `multiple`          | `false \| true`                                                                                                                                                      | `false`                     | Use arrays for multiple values; default \[]                                                                                                                      |
| `size`              | `'sm' \| 'md' \| 'lg'`                                                                                                                                               | `'md'`                      | Control size                                                                                                                                                     |
| `status`            | `'error' \| 'warning'`                                                                                                                                               | —                           | Validation appearance                                                                                                                                            |
| `disabled`          | `boolean`                                                                                                                                                            | `false`                     | Disable interaction.                                                                                                                                             |
| `allowClear`        | `boolean`                                                                                                                                                            | `false`                     | Show a clear button                                                                                                                                              |
| `showSearch`        | `boolean`                                                                                                                                                            | `false`                     | Allow typing to filter options                                                                                                                                   |
| `filterOption`      | `boolean \| ((query: string, option: `[`SelectOption`](#selectoption)`) => boolean)`                                                                                 | `true`                      | Custom filtering; false supports external filtering                                                                                                              |
| `onSearch`          | `(query: string) => void`                                                                                                                                            | —                           | Search text changes                                                                                                                                              |
| `loading`           | `boolean`                                                                                                                                                            | `false`                     | Loading indicator                                                                                                                                                |
| `notFoundContent`   | `ReactNode`                                                                                                                                                          | —                           | Content when no options match                                                                                                                                    |
| `maxCount`          | `number`                                                                                                                                                             | —                           | Maximum selections; selected items remain removable                                                                                                              |
| `maxTagCount`       | `number \| 'responsive'`                                                                                                                                             | —                           | Maximum visible tags; responsive collapses them to the available width.                                                                                          |
| `tagWrap`           | `boolean`                                                                                                                                                            | `true`                      | Allow selected tags to wrap; false keeps one line and collapses overflow.                                                                                        |
| `allowCreate`       | `boolean`                                                                                                                                                            | `false`                     | Allow selecting a new option unless the query exactly matches an existing value or search text; also enables search.                                             |
| `onCreate`          | `(option: `[`SelectOption`](#selectoption)`) => void`                                                                                                                | —                           | Called with a newly selected option; it is kept internally, while the application updates options for persistence.                                               |
| `labelRender`       | `(option: `[`SelectOption`](#selectoption)`) => ReactNode`                                                                                                           | —                           | Customize the selected value.                                                                                                                                    |
| `optionRender`      | `(option: `[`SelectOption`](#selectoption)`) => ReactNode`                                                                                                           | —                           | Custom option content                                                                                                                                            |
| `tagRender`         | `(option: `[`SelectOption`](#selectoption)`, remove: () => void) => ReactNode`                                                                                       | —                           | Customize selected tags; use remove to request removal.                                                                                                          |
| `open`              | `boolean`                                                                                                                                                            | —                           | Control whether the panel is open.                                                                                                                               |
| `defaultOpen`       | `boolean`                                                                                                                                                            | `false`                     | Initial open state.                                                                                                                                              |
| `onOpenChange`      | `(open: boolean) => void`                                                                                                                                            | —                           | Option panel open-state changes                                                                                                                                  |
| `inputReadOnly`     | `boolean`                                                                                                                                                            | —                           | Disable typing while retaining panel selection.                                                                                                                  |
| `virtual`           | `boolean`                                                                                                                                                            | More than 100 options       | Render visible items only                                                                                                                                        |
| `listHeight`        | `number`                                                                                                                                                             | `248`                       | List height                                                                                                                                                      |
| `optionHeight`      | `number`                                                                                                                                                             | Theme and density dependent | Estimated virtual row height, calculated from the theme and density by default; actual rows are measured.                                                        |
| `popupWidth`        | `number \| string`                                                                                                                                                   | `'trigger'`                 | Popup width; trigger matches the trigger, auto fits content (and may be narrower), numbers specify fixed pixels; CSS lengths are also supported.                 |
| `popupMaxWidth`     | `number \| 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.                                                                                                                               |
| `popupClassName`    | `string`                                                                                                                                                             | —                           | Popup styling                                                                                                                                                    |
| `popupStyle`        | `CSSProperties`                                                                                                                                                      | —                           | 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.                                                                                                                |
| `name`              | `string`                                                                                                                                                             | —                           | Field name in native FormData.                                                                                                                                   |
| `form`              | `string`                                                                                                                                                             | —                           | ID of the associated native form.                                                                                                                                |
| `required`          | `boolean`                                                                                                                                                            | `false`                     | Require a non-empty value; compound controls validate once.                                                                                                      |
| `ref`               | `Ref<HTMLInputElement>`                                                                                                                                              | —                           | DOM reference                                                                                                                                                    |

### SelectOption

An option passed through options; value identifies the option.

| Property      | Type        | Default  | Description                                                                |
| ------------- | ----------- | -------- | -------------------------------------------------------------------------- |
| `value`       | `string`    | Required | Unique option value; empty strings are reserved.                           |
| `label`       | `ReactNode` | Required | Option content, as text or a React node.                                   |
| `disabled`    | `boolean`   | `false`  | Disable the option.                                                        |
| `searchLabel` | `string`    | —        | Plain search text; defaults to a string or numeric label, otherwise value. |

### SelectOptionGroup API

A labeled group containing Select options.

| Property  | Type                                           | Default  | Description               |
| --------- | ---------------------------------------------- | -------- | ------------------------- |
| `label`   | `ReactNode`                                    | Required | Visible label or content. |
| `options` | `readonly `[`SelectOption`](#selectoption)`[]` | Required | Available options.        |
