Basic Select

Build a single-select component from simple string options to a full-featured clearable select with object data.

String Options

The simplest possible select: an array of strings bound with v-model.

API Setup (String Options)

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

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

Basic String Select

<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', 'Orange', 'Mango']
</script>

<template>
  <div class="bs-demo">
    <SelectRoot v-model="selected">
      <SelectControl class="bs-control">
        <SelectInput placeholder="Pick a fruit..." class="bs-input" />
      </SelectControl>
      <SelectContent class="bs-content">
        <SelectOption
          v-for="fruit in fruits"
          :key="fruit"
          v-slot="{ selected: isSelected, active }"
          :value="fruit"
          :label="fruit"
          class="bs-option"
          :class="{
            'bs-option--selected': isSelected,
            'bs-option--active': active,
          }"
        >
          {{ fruit }}
        </SelectOption>
      </SelectContent>
    </SelectRoot>
    <p v-if="selected" class="bs-result">Selected: <strong>{{ selected }}</strong></p>
    <p class="demo-note">This styling is for demos only. The library ships zero CSS</p>
  </div>
</template>

<style scoped>
.bs-demo {
  max-width: 320px;
}

.bs-control {
  display: flex;
  align-items: center;
  border: 1px solid var(--vp-c-divider);
  border-radius: 8px;
  padding: 0.5rem 0.75rem;
  background: var(--vp-c-bg);
  transition: border-color 0.2s;
}

.bs-control:focus-within {
  border-color: var(--vp-c-brand-1);
  box-shadow: 0 0 0 2px var(--vp-c-brand-soft);
}

.bs-input {
  width: 100%;
  border: none;
  outline: none;
  font-size: 0.9375rem;
  background: transparent;
  color: var(--vp-c-text-1);
}

.bs-input::placeholder {
  color: var(--vp-c-text-3);
}

.bs-content {
  position: absolute;
  top: 100%;
  left: 0;
  right: 0;
  margin-top: 4px;
  background: var(--vp-c-bg);
  border: 1px solid var(--vp-c-divider);
  border-radius: 8px;
  box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -2px rgba(0, 0, 0, 0.1);
  max-height: 200px;
  overflow-y: auto;
  z-index: 50;
  padding: 4px;
}

.bs-option {
  padding: 0.5rem 0.75rem;
  border-radius: 4px;
  cursor: pointer;
  font-size: 0.9375rem;
  color: var(--vp-c-text-1);
  transition: background-color 0.15s;
}

.bs-option--active {
  background-color: var(--vp-c-brand-soft);
}

.bs-option--selected {
  font-weight: 600;
  color: var(--vp-c-brand-1);
}

.bs-result {
  margin-top: 0.75rem;
  font-size: 0.875rem;
  color: var(--vp-c-text-2);
}
</style>

Minimal Pattern

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

For string options, :value and :label are the same string. The label prop is used for filtering. When a user types in the input, options are matched against their label.

Need the full setup/import boilerplate? See Quick Start.

Object Options

When your options are objects, use label-key and value-key on SelectRoot to tell the component which fields to use.

Object Options with label-key / value-key

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

interface Country {
  code: string
  name: string
}

const selected = ref<string | null>(null)
const countries: Country[] = [
  { code: 'au', name: 'Australia' },
  { code: 'br', name: 'Brazil' },
  { code: 'ca', name: 'Canada' },
  { code: 'de', name: 'Germany' },
  { code: 'fr', name: 'France' },
  { code: 'jp', name: 'Japan' },
  { code: 'uk', name: 'United Kingdom' },
]
</script>

<template>
  <div class="bo-demo">
    <SelectRoot
      v-model="selected"
      :items="countries"
      label-key="name"
      value-key="code"
    >
      <SelectControl class="bo-control">
        <SelectInput placeholder="Select a country..." class="bo-input" />
      </SelectControl>
      <SelectContent class="bo-content">
        <SelectOption
          v-for="country in countries"
          :key="country.code"
          v-slot="{ selected: isSelected, active }"
          :value="country.code"
          :label="country.name"
          class="bo-option"
          :class="{
            'bo-option--selected': isSelected,
            'bo-option--active': active,
          }"
        >
          {{ country.name }}
        </SelectOption>
      </SelectContent>
    </SelectRoot>
    <p class="bo-result">
      Selected code: <strong>{{ selected ?? 'none' }}</strong>
    </p>
    <p class="demo-note">This styling is for demos only. The library ships zero CSS</p>
  </div>
</template>

<style scoped>
.bo-demo {
  max-width: 320px;
}

.bo-control {
  display: flex;
  align-items: center;
  border: 1px solid var(--vp-c-divider);
  border-radius: 8px;
  padding: 0.5rem 0.75rem;
  background: var(--vp-c-bg);
  transition: border-color 0.2s;
}

.bo-control:focus-within {
  border-color: var(--vp-c-brand-1);
  box-shadow: 0 0 0 2px var(--vp-c-brand-soft);
}

.bo-input {
  width: 100%;
  border: none;
  outline: none;
  font-size: 0.9375rem;
  background: transparent;
  color: var(--vp-c-text-1);
}

.bo-input::placeholder {
  color: var(--vp-c-text-3);
}

.bo-content {
  position: absolute;
  top: 100%;
  left: 0;
  right: 0;
  margin-top: 4px;
  background: var(--vp-c-bg);
  border: 1px solid var(--vp-c-divider);
  border-radius: 8px;
  box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -2px rgba(0, 0, 0, 0.1);
  max-height: 200px;
  overflow-y: auto;
  z-index: 50;
  padding: 4px;
}

.bo-option {
  padding: 0.5rem 0.75rem;
  border-radius: 4px;
  cursor: pointer;
  font-size: 0.9375rem;
  color: var(--vp-c-text-1);
  transition: background-color 0.15s;
}

.bo-option--active {
  background-color: var(--vp-c-brand-soft);
}

.bo-option--selected {
  font-weight: 600;
  color: var(--vp-c-brand-1);
}

.bo-result {
  margin-top: 0.75rem;
  font-size: 0.875rem;
  color: var(--vp-c-text-2);
}
</style>

How Object Binding Works

<SelectRoot
  v-model="selected"
  :items="countries"
  label-key="name"
  value-key="code"
>

Prop	Purpose
:items	The full array of option objects. Used for label resolution when the dropdown is closed.
label-key	Which field to display and filter by (e.g. "name")
value-key	Which field becomes the v-model value (e.g. "code")

With value-key="code", the v-model value will be "au", "br", etc., not the full object.

Each SelectOption still receives the individual :value and :label:

<SelectOption
  v-for="country in countries"
  :key="country.code"
  :value="country.code"
  :label="country.name"
>
  {{ country.name }}
</SelectOption>

Clearable with Trigger and Empty State

Add a clear button, a dropdown toggle trigger, and a "no results" message for a complete select experience.

Clearable Select with Trigger and Empty State

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

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

<template>
  <div class="bc-demo">
    <SelectRoot v-model="selected" placeholder="Search fruits...">
      <SelectControl class="bc-control">
        <SelectInput class="bc-input" />
        <SelectClear v-if="selected" class="bc-clear">x</SelectClear>
        <SelectTrigger class="bc-trigger">
          <svg width="12" height="12" viewBox="0 0 12 12" fill="none">
            <path d="M3 4.5L6 7.5L9 4.5" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
          </svg>
        </SelectTrigger>
      </SelectControl>
      <SelectContent class="bc-content">
        <SelectOption
          v-for="fruit in fruits"
          :key="fruit"
          v-slot="{ selected: isSelected, active }"
          :value="fruit"
          :label="fruit"
          class="bc-option"
          :class="{
            'bc-option--selected': isSelected,
            'bc-option--active': active,
          }"
        >
          {{ fruit }}
        </SelectOption>
        <SelectEmpty class="bc-empty">No fruits match your search</SelectEmpty>
      </SelectContent>
    </SelectRoot>
    <p class="bc-result">
      Selected: <strong>{{ selected ?? 'nothing' }}</strong>
    </p>
    <p class="demo-note">This styling is for demos only. The library ships zero CSS</p>
  </div>
</template>

<style scoped>
.bc-demo {
  max-width: 320px;
}

.bc-control {
  display: flex;
  align-items: center;
  gap: 0.25rem;
  border: 1px solid var(--vp-c-divider);
  border-radius: 8px;
  padding: 0.5rem 0.75rem;
  background: var(--vp-c-bg);
  transition: border-color 0.2s;
}

.bc-control:focus-within {
  border-color: var(--vp-c-brand-1);
  box-shadow: 0 0 0 2px var(--vp-c-brand-soft);
}

.bc-input {
  flex: 1;
  min-width: 0;
  border: none;
  outline: none;
  font-size: 0.9375rem;
  background: transparent;
  color: var(--vp-c-text-1);
}

.bc-input::placeholder {
  color: var(--vp-c-text-3);
}

.bc-clear {
  display: flex;
  align-items: center;
  justify-content: center;
  width: 20px;
  height: 20px;
  padding: 0;
  border: none;
  border-radius: 50%;
  background: var(--vp-c-bg-soft);
  color: var(--vp-c-text-3);
  font-size: 0.75rem;
  cursor: pointer;
  transition: background-color 0.15s, color 0.15s;
}

.bc-clear:hover {
  background: var(--vp-c-divider);
  color: var(--vp-c-text-1);
}

.bc-trigger {
  display: flex;
  align-items: center;
  padding: 0;
  border: none;
  background: transparent;
  color: var(--vp-c-text-3);
  cursor: pointer;
}

.bc-content {
  position: absolute;
  top: 100%;
  left: 0;
  right: 0;
  margin-top: 4px;
  background: var(--vp-c-bg);
  border: 1px solid var(--vp-c-divider);
  border-radius: 8px;
  box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -2px rgba(0, 0, 0, 0.1);
  max-height: 200px;
  overflow-y: auto;
  z-index: 50;
  padding: 4px;
}

.bc-option {
  padding: 0.5rem 0.75rem;
  border-radius: 4px;
  cursor: pointer;
  font-size: 0.9375rem;
  color: var(--vp-c-text-1);
  transition: background-color 0.15s;
}

.bc-option--active {
  background-color: var(--vp-c-brand-soft);
}

.bc-option--selected {
  font-weight: 600;
  color: var(--vp-c-brand-1);
}

.bc-empty {
  padding: 0.75rem;
  text-align: center;
  font-size: 0.875rem;
  color: var(--vp-c-text-3);
}

.bc-result {
  margin-top: 0.75rem;
  font-size: 0.875rem;
  color: var(--vp-c-text-2);
}
</style>

Additional Components

Component	Purpose
SelectClear	Button that resets the value to null. Renders as <button> by default.
SelectTrigger	Button that toggles the dropdown open/closed.
SelectEmpty	Shown when filtering produces zero visible options.

<SelectControl>
  <SelectInput />
  <SelectClear v-if="selected">x</SelectClear>
  <SelectTrigger>
    <!-- chevron icon -->
  </SelectTrigger>
</SelectControl>

SelectClear is conditionally rendered with v-if. Show it only when there's a value to clear.

SelectEmpty goes inside SelectContent:

<SelectContent>
  <SelectOption v-for="..." />
  <SelectEmpty>No results found</SelectEmpty>
</SelectContent>

Scoped Slot Props

Every SelectOption exposes scoped slot props for conditional styling:

<SelectOption v-slot="{ selected, active, disabled, option }">
  {{ option }}
</SelectOption>

Prop	Type	Description
selected	boolean	Whether this option is currently selected
active	boolean	Whether this option is keyboard-highlighted
disabled	boolean	Whether this option is disabled
option	unknown	The raw value passed to :value

Next Steps

• Multi-Select
• Custom Filtering
• Controlled State