---
title: "NativeSelect"
description: "A native select element with the library field treatment."
category: "Form & Input"
slug: native-select
url: /components/native-select
since: "0.2.0"
status: "stable"
---

# NativeSelect

A native select element with the library field treatment.

## Import

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

## Preview

A labelled select with a placeholder and helper text.

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

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

<div class="field-row">
	<NativeSelect
		label="Region"
		placeholder="Choose a region"
		options={['eu-west', 'us-east', 'ap-south']}
		bind:value={region}
		helper="Latency is measured from the nearest edge."
	/>
</div>

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

## Usage

- Use when the platform picker is preferable to the custom `Select`.
- `options` accepts strings or `{ value, label, disabled }`; `placeholder` adds a disabled first option.
- Pass `children` with `<option>` elements to replace `options`.

## Examples

### Option objects

Labels differ from values and individual options can be disabled.

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

	let plan = $state('pro');

	const options = [
		{ value: 'free', label: 'Free — 1 project' },
		{ value: 'pro', label: 'Pro — 10 projects' },
		{ value: 'team', label: 'Team — unlimited' },
		{ value: 'enterprise', label: 'Enterprise — contact us', disabled: true }
	];
</script>

<div class="field-row">
	<NativeSelect label="Plan" {options} bind:value={plan} helper="Change the plan at any time." />
</div>

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

### States

Error and disabled treatments share the same frame.

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

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

<div class="stack">
	<NativeSelect
		label="Environment"
		placeholder="Choose an environment"
		options={['staging', 'production']}
		bind:value={errorValue}
		error="An environment is required."
	/>
	<NativeSelect
		label="Region"
		options={['eu-west', 'us-east']}
		value="eu-west"
		disabled
		helper="Locked by the organization policy."
	/>
</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` | `NativeSelectOption[]` | `[]` | Options to render. Strings are used as both value and label. |
| `value` **bindable** | `string` | `''` | Selected value. Bind with `bind:value`. |
| `placeholder` | `string` | `''` | Disabled first option shown while no value is selected. |
| `label` | `string` | `''` | Visible label above the select. |
| `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. |
| `disabled` | `boolean` | `false` | Disables interaction and applies the disabled treatment. |
| `required` | `boolean` | `false` | Marks the field as required. |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Control size. |
| `id` | `string` | `''` | Element id. A generated id is used when omitted. |
| `className` | `string` | `''` | Extra classes merged onto the root element. |

`class`, `id`, `style`, `aria-*`, and `data-*` are forwarded through rest props.

### Events

| Event | Handler type | Description |
| --- | --- | --- |
| `change` | `(e: Event) => void` | Called with the native change event. |

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

### Snippets

| Snippet | Type | Description |
| --- | --- | --- |
| `children` | `Snippet` | Custom option elements, used instead of `options`. |

### Types

#### `NativeSelectOption`

An option value or a full option object.

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

### Tokens used

`--iv_border` · `--iv_border-error` · `--iv_border-focus` · `--iv_border-hover` · `--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_error` · `--iv_error-surface` · `--iv_font-mono` · `--iv_font-ui` · `--iv_foreground` · `--iv_foreground-dim` · `--iv_radius-sm` · `--iv_ring` · `--iv_ring-width` · `--iv_spacing-2xs` · `--iv_spacing-lg` · `--iv_spacing-sm` · `--iv_spacing-xs` · `--iv_surface-raised` · `--iv_text-base` · `--iv_text-body-sm` · `--iv_text-label` · `--iv_text-lg` · `--iv_text-sm` · `--iv_transition-base` · `--iv_weight-medium`

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

### CSS hooks

`.iv-chevron` · `.iv-disabled` · `.iv-error-message` · `.iv-has-error` · `.iv-helper-message` · `.iv-label` · `.iv-lg` · `.iv-message` · `.iv-native-select` · `.iv-required-mark` · `.iv-sm`

## Accessibility

| Keys | Action |
| --- | --- |
| `Tab` | Moves focus to the select. |
| `Arrow keys` | Move through options in the platform picker. |
| `Enter / Space` | Opens the picker. |

- The label is associated through a generated id, or pass `id` explicitly.
- Error text is linked with `aria-describedby` and the select gets `aria-invalid`.

## Related

- [Select](/components/select.md)
- [Input](/components/input.md)
- [Field](/components/field.md)
- [InputGroup](/components/input-group.md)