Native Select

Accessible, unstyled native select with controlled and uncontrolled selection.

Minimal setup

Use a Vue 3.5+ project with Vue SFC compilation configured (see Vite+ integration).

vp install @vizejs/ui

Add the public import below to <script setup lang="ts">. Components provide behavior without styles; the preview uses optional Paper styles.

import { NativeSelect } from "@vizejs/ui/native-select";

Or copy the source into your project with vize lib pull native-select (see Source Distribution).

Try it

This is the basic example maintained with the component source, using the public package imports. The preview adds the optional Paper styles.

Open the interactive example · Styling these components

Copy the example

<!-- Native select bound with v-model, rendering options from data with one disabled choice. -->
<script setup lang="ts">
import { ref, useId } from "vue";

import { NativeSelect, type NativeSelectOption, type NativeSelectValue } from "@vizejs/ui/native-select";

const plan = ref<NativeSelectValue>("team");
const selectId = useId();
const plans: readonly NativeSelectOption[] = [
  { value: "starter", label: "Starter — free" },
  { value: "team", label: "Team — $12 per seat" },
  { value: "enterprise", label: "Enterprise — contact sales", disabled: true },
];
</script>

<template>
  <div>
    <label :for="selectId">Billing plan</label>
    <NativeSelect :id="selectId" v-model="plan" name="plan" :options="plans" />
    <output :for="selectId">Selected plan: {{ plan }}</output>
  </div>
</template>

API

NativeSelect

Source: src/families/selection/native-select/native-select.vue

Props

Events

Slots

Exposed

Behavior

Contract

native-select.vue is a headless primitive over the platform <select> element. It does not portal, render overlays, own typeahead, or replace browser selection UI. Consumers style the native element and prop-rendered options through parts, slots, CSS, and data attributes.

readOnly is intentionally unsupported because native <select> has no readonly state. Consumers that need a non-editable submitted value should keep the component controlled and ignore changes, or render disabled UI with a separate hidden form value when that submission behavior is required.

Public Surface

Normative Behavior

SSR

Generated ids use the deterministic-id primitive. Isolated SSR requests must produce byte-identical markup for the same tree, including selected prop-rendered options, and hydration must not replace the rendered native select.