NativeSelect
A native select element with the library field treatment.
import { NativeSelect } from '@elluzion/iv-ui'; 01 Preview
Basic
A labelled select with a placeholder and helper text.
Source· svelte Show Hide
<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>02 Usage
- Use when the platform picker is preferable to the custom
Select. optionsaccepts strings or{ value, label, disabled };placeholderadds a disabled first option.- Pass
childrenwith<option>elements to replaceoptions.
03 Examples
Option objects
Labels differ from values and individual options can be disabled.
Source· svelte Show Hide
<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.
Source· svelte Show Hide
<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>04 API
import { NativeSelect } from '@elluzion/iv-ui';Props
12 props · 1 events · 1 snippets| 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 |
|---|---|---|
| onchange | (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.
type NativeSelectOption = string | { value: string; label?: string; disabled?: boolean };05 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
idexplicitly. - Error text is linked with
aria-describedbyand the select getsaria-invalid.
06 Tokens & CSS hooks
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
Class 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