---
title: "Select"
description: "A custom listbox with search, multiple selection, and clearing."
category: "Form & Input"
slug: select
url: /components/select
since: "0.1.0"
status: "stable"
---

# Select

A custom listbox with search, multiple selection, and clearing.

## Import

```svelte
import { Select } from '@elluzion/iv-ui';
```

## Preview

A labelled single select with a placeholder.

```svelte
<script lang="ts">
	import { Select } from '@elluzion/iv-ui';

	let branch = $state('');
</script>

<div class="field-row">
	<Select
		label="Branch"
		placeholder="Choose a branch"
		options={['main', 'release', 'feat/docs-site']}
		bind:value={branch}
		helper="Deploys use the selected branch."
	/>
</div>

<style>
	.field-row {
		width: 100%;
		max-width: 320px;
	}
</style>
```

## Usage

- `options` accepts strings or `{ value, label, disabled }`.
- `multiple` turns `value` into an array; `searchable` adds a filter field.
- Bind `value`; `onchange` fires with the committed selection.

## Examples

### Multiple

Selected values render as chips and `value` is an array.

```svelte
<script lang="ts">
	import { Select } from '@elluzion/iv-ui';

	let services = $state<string[]>(['logs', 'metrics']);
</script>

<div class="field-row">
	<Select
		label="Services"
		multiple
		options={['logs', 'metrics', 'traces', 'alerts', 'backups']}
		bind:value={services}
		helper="Selected services receive the retention policy."
	/>
	<p class="readout">selected: {services.join(', ') || '—'}</p>
</div>

<style>
	.field-row {
		display: flex;
		flex-direction: column;
		gap: var(--iv_spacing-md);
		width: 100%;
		max-width: 360px;
	}

	.readout {
		margin: 0;
		font-family: var(--iv_font-mono);
		font-size: var(--iv_text-sm);
		color: var(--iv_foreground-dim);
	}
</style>
```

### Searchable

`searchable` filters the list as you type.

```svelte
<script lang="ts">
	import { Select } from '@elluzion/iv-ui';

	let member = $state('');

	const options = [
		'Ada Lovelace',
		'Grace Hopper',
		'Alan Turing',
		'Katherine Johnson',
		'Margaret Hamilton',
		'Radia Perlman'
	];
</script>

<div class="field-row">
	<Select label="Reviewer" searchable placeholder="Search people…" {options} bind:value={member} />
</div>

<style>
	.field-row {
		width: 100%;
		max-width: 320px;
	}
</style>
```

### States

Clearable, error, and disabled variants.

```svelte
<script lang="ts">
	import { Select } from '@elluzion/iv-ui';

	let region = $state('eu-west');
	let environment = $state('');
</script>

<div class="stack">
	<Select
		label="Region"
		clearable
		options={['eu-west', 'us-east', 'ap-south']}
		bind:value={region}
	/>
	<Select
		label="Environment"
		placeholder="Choose an environment"
		options={['staging', 'production']}
		bind:value={environment}
		error="An environment is required."
	/>
	<Select label="Organization" options={['orbital']} value="orbital" disabled />
</div>

<style>
	.stack {
		display: flex;
		flex-direction: column;
		gap: var(--iv_spacing-lg);
		width: 100%;
		max-width: 320px;
	}
</style>
```

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `options` **required** | `SelectOption[]` | `[]` | Options to render. Strings are used as both value and label. |
| `value` **bindable** | `string \| string[]` | `''` | Selected value(s). Bind with `bind:value`. |
| `multiple` | `boolean` | `false` | Allows several values; `value` becomes an array. |
| `searchable` | `boolean` | `false` | Adds a filter field to the option list. |
| `clearable` | `boolean` | `false` | Shows a reset button while a value is selected. |
| `disabled` | `boolean` | `false` | Disables interaction and applies the disabled treatment. |
| `required` | `boolean` | `false` | Marks the field as required. |
| `placeholder` | `string` | `'Select…'` | Text shown while nothing is selected. |
| `label` | `string` | `''` | Visible label for the control. |
| `error` | `string` | `''` | Error message. Switches the control to the error treatment. |
| `helper` | `string` | `''` | Helper text shown below the control. |
| `name` | `string` | `''` | Form field name submitted with the surrounding form. |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Control size. |

### Events

| Event | Handler type | Description |
| --- | --- | --- |
| `change` | `(e: CustomEvent<{ value: string \| string[] }>) => void` | Called with `{ value }` after the selection changes. |
| `focus` | `(e: FocusEvent) => void` | Called when the trigger receives focus. |
| `blur` | `(e: FocusEvent) => void` | Called when the trigger loses focus. |
| `keydown` | `(e: KeyboardEvent) => void` | Called on keydown inside the trigger. |

The legacy `on:name` form is accepted for every event.

### Types

#### `SelectOption`

An option value or a full option object.

```ts
type SelectOption = string | { value: string; label?: string; disabled?: boolean };
```

### Tokens used

`--iv_border` · `--iv_border-error` · `--iv_border-focus` · `--iv_border-hover` · `--iv_control-md` · `--iv_control-pad-x` · `--iv_control-pad-x-lg` · `--iv_control-pad-x-sm` · `--iv_control-pad-y` · `--iv_control-pad-y-lg` · `--iv_control-pad-y-sm` · `--iv_cursor` · `--iv_disabled-opacity` · `--iv_ease-in-out` · `--iv_ease-out` · `--iv_error` · `--iv_error-surface` · `--iv_font-mono` · `--iv_font-ui` · `--iv_foreground` · `--iv_foreground-dim` · `--iv_leading-loose` · `--iv_outline-offset` · `--iv_outline-width` · `--iv_radius-sm` · `--iv_ring` · `--iv_ring-width` · `--iv_scrollbar-size` · `--iv_select-dropdown-max-h` · `--iv_shadow-md` · `--iv_spacing-2xs` · `--iv_spacing-sm` · `--iv_spacing-xs` · `--iv_surface-overlay` · `--iv_surface-raised` · `--iv_text-base` · `--iv_text-body-sm` · `--iv_text-chips` · `--iv_text-label` · `--iv_text-lg` · `--iv_text-sm` · `--iv_transition-base` · `--iv_transition-fast`

See the [token reference](/foundations/tokens.md) for values.

### CSS hooks

`.iv-chevron` · `.iv-chip` · `.iv-chip-placeholder` · `.iv-chips` · `.iv-clear-btn` · `.iv-disabled` · `.iv-dropdown` · `.iv-error-message` · `.iv-has-error` · `.iv-helper-message` · `.iv-label` · `.iv-lg` · `.iv-message` · `.iv-open` · `.iv-placeholder` · `.iv-required-mark` · `.iv-root` · `.iv-search` · `.iv-search-icon` · `.iv-select-options` · `.iv-sm` · `.iv-trigger` · `.iv-trigger-label`

## Accessibility

| Keys | Action |
| --- | --- |
| `Enter / Space / ArrowDown` | Opens the list. |
| `Arrow keys` | Move the active option. |
| `Enter` | Selects the active option. |
| `Escape` | Closes the list. |

- The trigger is a `combobox` with `aria-expanded`, `aria-controls`, and `aria-activedescendant`.
- Options use the `option` role inside a `listbox`.
- Error text is linked through `aria-describedby`; the trigger gets `aria-invalid`.

## Related

- [NativeSelect](/components/native-select.md)
- [Menu](/components/menu.md)
- [Input](/components/input.md)
- [Field](/components/field.md)