Select

Accessible, unstyled custom Select: a select-only combobox with a typed listbox popup.

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 { Select, SelectRoot, SelectContent, SelectGroup, SelectItem, SelectItemIndicator, SelectLabel, SelectScrollButton, SelectSeparator, SelectTrigger, SelectValue, SelectViewport, SelectVirtualizer } from "@vizejs/ui/select";

Or copy the source into your project with vize lib pull 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

<!-- Controlled select-only combobox with a placeholder, a labelled group, and selection marks. -->
<script setup lang="ts">
import { ref, useId } from "vue";

import {
  Select,
  SelectContent,
  SelectGroup,
  SelectItem,
  SelectItemIndicator,
  SelectLabel,
  SelectTrigger,
  SelectValue,
  SelectViewport,
} from "@vizejs/ui/select";

const timezones = ["Asia/Tokyo", "Europe/Paris", "America/New_York"];
const timezone = ref<string | null>(null);
const labelId = useId();
</script>

<template>
  <div>
    <span :id="labelId">Time zone</span>
    <Select v-model="timezone" :items="timezones" name="timezone" placeholder="Choose a time zone">
      <SelectTrigger :aria-labelledby="labelId"><SelectValue /></SelectTrigger>
      <SelectContent>
        <SelectViewport>
          <SelectGroup>
            <SelectLabel>Common zones</SelectLabel>
            <SelectItem v-for="zone in timezones" :key="zone" :value="zone">
              {{ zone }}
              <SelectItemIndicator>✓</SelectItemIndicator>
            </SelectItem>
          </SelectGroup>
        </SelectViewport>
      </SelectContent>
    </Select>
  </div>
</template>

API

Select<T, Multiple extends boolean = false>

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

Props

Events

Slots

Exposed

SelectRoot<T, Multiple extends boolean = false>

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

Props

Events

Slots

Exposed

SelectContent

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

Props

Events

Slots

Exposed

SelectGroup

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

Props

Slots

SelectItem<T>

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

Props

Slots

Exposed

SelectItemIndicator

Source: src/families/selection/select/select-item-indicator.vue

Props

Slots

SelectLabel

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

Slots

SelectScrollButton

Source: src/families/selection/select/select-scroll-button.vue

Props

Slots

Exposed

SelectSeparator

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

Slots

SelectTrigger

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

Props

Slots

Exposed

SelectValue

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

Props

Slots

SelectViewport

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

Slots

Exposed

SelectVirtualizer<T>

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

Props

Slots

Exposed

Behavior

Contract

Select is a headless, strongly typed custom select built on the WAI-ARIA APG select-only combobox pattern. select-root.vue is generic over the option value type T and a Multiple literal: omitting multiple (or passing false) makes the model T | null; multiple: true makes it readonly T[]. Values may be any type; by compares them by property key or custom equality.

select-trigger.vue renders a native <button role="combobox"> that keeps DOM focus for the whole interaction and exposes the highlighted option through aria-activedescendant. select-content.vue renders the role="listbox" popup through Portal, Presence, Positioner, and a dismissable layer; options (select-item.vue) register with the shared collection registry and composite navigation used by Listbox. select-value.vue renders the selected label or placeholder, select-item-indicator.vue a selection mark, select-group.vue/select-label.vue labelled groups, select-separator.vue a decorative divider, select-viewport.vue the scroll container, select-scroll-button.vue hover-to-scroll affordances, and select-virtualizer.vue a windowed option list for large collections.

The root always renders a hidden, aria-hidden native <select> that mirrors the selection for form submission, required validation, form= association, form reset, and autofill. No CSS is shipped; every part publishes data-vize-ui, data-state, and state-specific data attributes.

Public Surface

Normative Behavior

Options rendered by SelectVirtualizer carry an absolute index; the collection orders options by index, so any option mixed into the same popup (for example a pinned option before the virtual window) must pass index too.

SSR

Ids derive from the deterministic-id primitive. Closed and open trees, and a virtual window laid out against initialViewportHeight, render byte-identical markup across isolated requests and hydrate without warnings or node replacement (renders byte-identical closed Select markup with SSR labels and form mirror, renders byte-identical open Select markup in place before the portal hydrates, hydrates closed and open Selects without mismatches, server-renders and hydrates a deterministic virtual window). Pass itemText so closed triggers render the right label before any option has mounted. Scroll buttons measure after mount, so they render hidden in server markup.