Author plain option and optgroup children and the component mirrors them into a real native select, so the platform picker, typeahead and mobile wheels all work unchanged. Reach for Select instead when options need icons, descriptions or custom layout. Insert, remove or reorder the authored nodes to update the picker.
Placeholder
placeholder adds a disabled empty first option, so nothing is chosen until the person picks. Add required and the empty value fails validation on submit.
Placeholder
Default density
Compact density
Restart from the initial state
Show the copyable source
multiple renders the native multi-selection listbox and submits one entry per selected value, in option order. Set the value as an array through the value property.
Multiple
Default density
Compact density
Restart from the initial state
Show the copyable source
<tp-field label="Notify on" description="Hold Ctrl or ⌘ to select several." style="max-inline-size:22rem">
<tp-native-select name="events" multiple>
<option value="deploy" selected>Deploy finished</option>
<option value="failed" selected>Build failed</option>
<option value="review">Review requested</option>
<option value="mention">Mentioned in a comment</option>
</tp-native-select>
</tp-field>
Forms
Native Select participates in forms like Input: it submits its name, resets to its default and restores on navigation. Listen for tp-value-change to react to changes.
Form value
Default density
Compact density
Restart from the initial state
Show the copyable source
Set value to own the selection and accept each proposal in onValueChange by assigning event.detail.value. Leave value unchanged to reject a pick; the native picker snaps back to the committed option. Controlled values absent from the options have no native selection and no submitted entry.
Controlled value
Default density
Compact density
Restart from the initial state
Show the copyable source
<div style="display:grid;gap:var(--tp-space-3);max-inline-size:22rem">
<tp-field label="Seat limit" description="18 members are active in this workspace.">
<tp-native-select id="native-select-seats" value="25">
<option value="10">10 seats — $96/mo</option>
<option value="25">25 seats — $240/mo</option>
<option value="50">50 seats — $480/mo</option>
</tp-native-select>
</tp-field>
<output id="native-select-seats-note" style="color:var(--tp-muted-foreground);font-size:var(--tp-text-sm)">Current plan: 25 seats.</output>
</div>
<script type="module">
const select = document.querySelector('#native-select-seats');
const note = document.querySelector('#native-select-seats-note');
const activeMembers = 18;
select.onValueChange = (event) => {
if (event.defaultPrevented || event.detail.cancelled) return;
const seats = Number(event.detail.value);
if (seats < activeMembers) {
note.textContent = `Remove ${activeMembers - seats} members before dropping to ${seats} seats.`;
return;
}
select.value = event.detail.value;
note.textContent = `Current plan: ${seats} seats.`;
};
</script>
States
Disabled, read-only and invalid
Default density
Compact density
Restart from the initial state
Show the copyable source
<div style="display:grid;gap:var(--tp-space-4);max-inline-size:22rem">
<tp-field label="Plan" disabled>
<tp-native-select default-value="team">
<option value="team">Team</option>
<option value="enterprise">Enterprise</option>
</tp-native-select>
</tp-field>
<tp-field label="Currency" description="Set by your billing country.">
<tp-native-select readonly default-value="eur">
<option value="eur">Euro (EUR)</option>
<option value="usd">US dollar (USD)</option>
</tp-native-select>
</tp-field>
<tp-field label="Timezone" error="Choose a timezone to schedule reports." invalid>
<tp-native-select placeholder="Select a timezone">
<option value="utc">UTC</option>
<option value="cet">Central European Time</option>
</tp-native-select>
</tp-field>
</div>
Native selects have no read-only mode, so readonly blocks changes while keeping the value focusable and submitted. Disabled omits it from form data.
API Reference
Every element also accepts motion-policy.
Attributes
AttributePropertyTypeDefaultDescriptiondefault-valuedefaultValueNativeSelectValue | undefined—The initial value of an uncontrolled select, restored on form reset; an array with multiple.multiplemultiplebooleanfalseSelects several values with the native list box instead of a dropdown; the value becomes an
array.placeholderplaceholderstring''A disabled first option shown while nothing is selected.labellabelstring'Options'Accessible name when no Field labels the select.sizesize'sm' | 'default''default'Height and text size, matching Input's sizes.
Properties
PropertyTypeDefaultDescriptiononValueChange((event: TpValueChangeEvent<NativeSelectValue>) => void) | undefined—Called with each proposed value before tp-value-change; a controlled owner accepts it by
setting value.hostPropertiesRecord<string, unknown>{}Attributes, properties and listeners applied to the inner native select.controlledread-onlyboolean—Whether the application controls value.selectedOptionsread-onlyHTMLCollectionOf<HTMLOptionElement> | null—The native select's selected options.optionsread-onlyHTMLOptionsCollection | null—The native select's options.selectedIndexnumber—Index of the first selected option, as on a native select; setting it proposes that option.
Events
EventTypeDescriptiontp-value-changeTpValueChangeEvent<string | readonly string[]>Cancelable proposal of a new value, before it commits; detail.value, detail.previousValue and detail.reason.tp-field-valueCustomEvent<{ value: string | readonly string[]; previousValue: string | readonly string[]; reason: ChangeReason; }>After a value commits; an enclosing Field tracks its dirty state from it.
Methods
MethodReturnsDescriptionsetValue(value)booleanProposes a value as if chosen in the picker, and returns whether it was accepted.setCustomValidity(message)voidSets a custom validation message; an empty string clears it.
Slots
SlotDescriptiondefaultNative option, optgroup and hr elements declaring the choices.indicatorReplaces the chevron at the end of a single select.
CSS parts
PartDescription::part(native-select)The wrapper around the native select and its chevron.::part(native-select-control)The native select element.::part(native-select-indicator)The chevron at the end of a single select.::part(native-select-option)A native option, including the placeholder.::part(native-select-option-group)A native option group.
Related
Components, widgets and patterns that use this one.