vue-superselect

Headless, accessible, TypeScript-first select/combobox for Vue 3.

Zero runtime CSS. Full keyboard navigation. WAI-ARIA combobox pattern. Dual API: compound components or useSelect() composable.

Documentation

Install

npm install vue-superselect

Vue 3.5+ required. @floating-ui/vue is an optional peer dependency for smart dropdown positioning.

Quick Start

<script setup lang="ts">
import { ref } from 'vue'
import {
  SelectRoot,
  SelectControl,
  SelectInput,
  SelectContent,
  SelectOption,
} from 'vue-superselect'

const selected = ref<string | null>(null)
const fruits = ['Apple', 'Banana', 'Cherry', 'Grape', 'Orange']
</script>

<template>
  <SelectRoot v-model="selected">
    <SelectControl>
      <SelectInput placeholder="Pick a fruit..." aria-label="Fruit" />
    </SelectControl>
    <SelectContent>
      <SelectOption
        v-for="fruit in fruits"
        :key="fruit"
        :value="fruit"
        :label="fruit"
      >
        {{ fruit }}
      </SelectOption>
    </SelectContent>
  </SelectRoot>
</template>

The library ships zero CSS. Add your own classes and styles.

Features

• Headless: no shipped CSS, full control over rendering via scoped slots
• Accessible: WAI-ARIA combobox pattern, keyboard navigation, screen reader announcements
• TypeScript: strict mode, full generic inference, typed props and slots
• Single and multi-select: v-model with multiple, tags, max limits, hideSelected
• Filtering: built-in case-insensitive filter, custom filter functions, debounce, IME-safe
• Positioning: optional @floating-ui/vue integration with auto-flip, teleport support
• Composable API: useSelect<T>() with prop getters for full DOM control
• Tree-shakeable: sideEffects: false, ESM + CJS builds, /*#__PURE__*/ annotations

Components

Component	Purpose
SelectRoot	State container. Manages selection, filtering, keyboard, and ARIA.
SelectControl	Wrapper around the input/tags area.
SelectInput	Search/filter input field.
SelectContent	Dropdown container with positioning.
SelectOption	Individual selectable option with scoped slot props.
SelectTag	Removable tag for multi-select.
SelectTrigger	Toggle button for the dropdown.
SelectClear	Button to clear the current selection.
SelectEmpty	Shown when no options match the filter.
SelectLiveRegion	Screen reader announcements.

Composable API

For full control over the rendered DOM:

import { useSelect } from 'vue-superselect'

const {
  getRootProps,
  getInputProps,
  getListboxProps,
  getOptionProps,
  isOpen,
  value,
  visibleItems,
} = useSelect({
  items: options,
  labelKey: 'label',
  valueKey: 'id',
})

Spread prop getters on your own elements:

<div v-bind="getRootProps()">
  <input v-bind="getInputProps()" />
  <ul v-bind="getListboxProps()">
    <li v-for="item in visibleItems" :key="item.id" v-bind="getOptionProps(item)">
      {{ item.label }}
    </li>
  </ul>
</div>

Keyboard Navigation

Key	Action
Arrow Down/Up	Navigate options
Enter	Select highlighted option
Escape	Close dropdown; pressing again clears input query
Tab	Move focus (or select highlighted option when selectOnTab is enabled)
Backspace	Remove last tag (multi-select, empty input)
Home/End	Jump to first/last option

Browser Support

Modern browsers (Chrome, Firefox, Safari, Edge). No IE11.

License

MIT