{"slug":"native-select","name":"NativeSelect","category":"Form & Input","summary":"A native select element with the library field treatment.","status":"stable","since":"0.2.0","import":"import { NativeSelect } from '@elluzion/iv-ui';","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`."],"props":[{"name":"options","type":"NativeSelectOption[]","default":"[]","description":"Options to render. Strings are used as both value and label.","required":false,"bindable":false},{"name":"value","type":"string","default":"''","description":"Selected value. Bind with `bind:value`.","required":false,"bindable":true},{"name":"placeholder","type":"string","default":"''","description":"Disabled first option shown while no value is selected.","required":false,"bindable":false},{"name":"label","type":"string","default":"''","description":"Visible label above the select.","required":false,"bindable":false},{"name":"error","type":"string","default":"''","description":"Error message. Switches the control to the error treatment.","required":false,"bindable":false},{"name":"helper","type":"string","default":"''","description":"Helper text shown below the control.","required":false,"bindable":false},{"name":"name","type":"string","default":"''","description":"Form field name submitted with the surrounding form.","required":false,"bindable":false},{"name":"disabled","type":"boolean","default":"false","description":"Disables interaction and applies the disabled treatment.","required":false,"bindable":false},{"name":"required","type":"boolean","default":"false","description":"Marks the field as required.","required":false,"bindable":false},{"name":"size","type":"'sm' | 'md' | 'lg'","default":"'md'","description":"Control size.","required":false,"bindable":false},{"name":"id","type":"string","default":"''","description":"Element id. A generated id is used when omitted.","required":false,"bindable":false},{"name":"className","type":"string","default":"''","description":"Extra classes merged onto the root element.","required":false,"bindable":false}],"events":[{"name":"change","type":"(e: Event) => void","default":null,"description":"Called with the native change event.","required":false,"bindable":false}],"snippets":[{"name":"children","type":"Snippet","default":null,"description":"Custom option elements, used instead of `options`.","required":false,"bindable":false}],"types":[{"name":"NativeSelectOption","kind":"type","code":"type NativeSelectOption = string | { value: string; label?: string; disabled?: boolean };","description":"An option value or a full option object."}],"manual":[],"tokens":["--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"],"cssHooks":["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":{"keyboard":[["Tab","Moves focus to the select."],["Arrow keys","Move through options in the platform picker."],["Enter / Space","Opens the picker."]],"notes":["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":[{"title":"Select","summary":"A custom listbox with search, multiple selection, and clearing.","url":"/components/select","kind":"Component"},{"title":"Input","summary":"A single-line text field with an optional label, helper, and error state.","url":"/components/input","kind":"Component"},{"title":"Field","summary":"Labels a custom control and renders its helper or error message.","url":"/components/field","kind":"Component"},{"title":"InputGroup","summary":"Joins an input with prefix and suffix addons inside one frame.","url":"/components/input-group","kind":"Component"}],"examples":[{"id":"basic","title":"Basic","description":"A labelled select with a placeholder and helper text.","code":"<script lang=\"ts\">\n\timport { NativeSelect } from '@elluzion/iv-ui';\n\n\tlet region = $state('');\n</script>\n\n<div class=\"field-row\">\n\t<NativeSelect\n\t\tlabel=\"Region\"\n\t\tplaceholder=\"Choose a region\"\n\t\toptions={['eu-west', 'us-east', 'ap-south']}\n\t\tbind:value={region}\n\t\thelper=\"Latency is measured from the nearest edge.\"\n\t/>\n</div>\n\n<style>\n\t.field-row {\n\t\twidth: 100%;\n\t\tmax-width: 320px;\n\t}\n</style>"},{"id":"options","title":"Option objects","description":"Labels differ from values and individual options can be disabled.","code":"<script lang=\"ts\">\n\timport { NativeSelect } from '@elluzion/iv-ui';\n\n\tlet plan = $state('pro');\n\n\tconst options = [\n\t\t{ value: 'free', label: 'Free — 1 project' },\n\t\t{ value: 'pro', label: 'Pro — 10 projects' },\n\t\t{ value: 'team', label: 'Team — unlimited' },\n\t\t{ value: 'enterprise', label: 'Enterprise — contact us', disabled: true }\n\t];\n</script>\n\n<div class=\"field-row\">\n\t<NativeSelect label=\"Plan\" {options} bind:value={plan} helper=\"Change the plan at any time.\" />\n</div>\n\n<style>\n\t.field-row {\n\t\twidth: 100%;\n\t\tmax-width: 320px;\n\t}\n</style>"},{"id":"states","title":"States","description":"Error and disabled treatments share the same frame.","code":"<script lang=\"ts\">\n\timport { NativeSelect } from '@elluzion/iv-ui';\n\n\tlet errorValue = $state('');\n</script>\n\n<div class=\"stack\">\n\t<NativeSelect\n\t\tlabel=\"Environment\"\n\t\tplaceholder=\"Choose an environment\"\n\t\toptions={['staging', 'production']}\n\t\tbind:value={errorValue}\n\t\terror=\"An environment is required.\"\n\t/>\n\t<NativeSelect\n\t\tlabel=\"Region\"\n\t\toptions={['eu-west', 'us-east']}\n\t\tvalue=\"eu-west\"\n\t\tdisabled\n\t\thelper=\"Locked by the organization policy.\"\n\t/>\n</div>\n\n<style>\n\t.stack {\n\t\tdisplay: flex;\n\t\tflex-direction: column;\n\t\tgap: var(--iv_spacing-lg);\n\t\twidth: 100%;\n\t\tmax-width: 320px;\n\t}\n</style>"}],"markdown":"/components/native-select.md","page":"/components/native-select"}