Multi-Select

Enable selecting multiple values with the multiple prop. The v-model becomes an array, the dropdown stays open between selections, and users can toggle options on and off.

Basic Multi-Select

Add multiple to SelectRoot and bind v-model to an array.

API Setup (Multi-Select)

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

const selected = ref([])
const skills = ['Vue', 'React', 'Svelte', 'Solid', 'Angular']
</script>

Basic Multi-Select

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

const selected = ref<string[]>([])
const skills = ['JavaScript', 'TypeScript', 'Vue', 'React', 'Node.js', 'Python', 'Go', 'Rust']

const display = computed(() =>
  selected.value.length === 0 ? '' : selected.value.join(', ')
)
</script>

<template>
  <div class="ms-demo">
    <div class="ms-layout">
      <SelectRoot id="docs-multi-basic" v-model="selected" multiple>
        <div class="ms-select">
          <SelectControl class="ms-control">
            <SelectInput placeholder="Select skills..." class="ms-input" />
          </SelectControl>
          <SelectContent class="ms-content">
            <SelectOption
              v-for="skill in skills"
              :key="skill"
              v-slot="{ selected: isSelected, active }"
              :value="skill"
              :label="skill"
              class="ms-option"
              :class="{
                'ms-option--selected': isSelected,
                'ms-option--active': active,
              }"
            >
              <span class="ms-check">{{ isSelected ? '&#10003;' : '' }}</span>
              {{ skill }}
            </SelectOption>
          </SelectContent>
        </div>
      </SelectRoot>
      <p class="ms-result">
        Selected ({{ selected.length }}): <strong>{{ display || 'none' }}</strong>
      </p>
    </div>
    <p class="demo-note">This styling is for demos only. The library ships zero CSS</p>
  </div>
</template>

<style scoped>
.ms-demo {
  max-width: 100%;
}

.ms-layout {
  display: flex;
  align-items: flex-start;
  gap: 1rem;
}

.ms-select {
  position: relative;
  width: 360px;
  max-width: 100%;
  min-width: 0;
}

.ms-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;
}

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

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

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

.ms-content {
  position: absolute;
  top: calc(100% + 4px);
  left: 0;
  right: 0;
  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: 240px;
  overflow-y: auto;
  z-index: 50;
  padding: 4px;
}

.ms-option {
  display: flex;
  align-items: center;
  gap: 0.5rem;
  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;
}

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

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

.ms-check {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  width: 16px;
  height: 16px;
  font-size: 0.75rem;
  color: var(--vp-c-brand-1);
}

.ms-result {
  margin-top: 0.5rem;
  flex: 1;
  min-width: 0;
  font-size: 0.875rem;
  color: var(--vp-c-text-2);
}

@media (max-width: 900px) {
  .ms-layout {
    display: block;
  }

  .ms-result {
    margin-top: 0.75rem;
  }
}
</style>

Key Differences from Single Select

Behavior	Single	Multi
v-model type	T | null	T[]
After selection	Dropdown closes	Dropdown stays open
Clicking selected option	No effect	Deselects (toggle)
Query	Preserved	Clears after each selection

<SelectRoot v-model="selected" multiple>
  <!-- same template structure as single select -->
</SelectRoot>

The only state-level difference is selected must be an array (ref([]) / selected: []).

Tags with Remove Buttons

Use SelectTag inside SelectControl's scoped slot to render removable tags for each selection.

Multi-Select with Tags

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

interface TeamMember {
  id: string
  name: string
}

const selected = ref<string[]>([])
const members: TeamMember[] = [
  { id: 'alice', name: 'Alice' },
  { id: 'bob', name: 'Bob' },
  { id: 'charlie', name: 'Charlie' },
  { id: 'diana', name: 'Diana' },
  { id: 'eve', name: 'Eve' },
  { id: 'frank', name: 'Frank' },
]
</script>

<template>
  <div class="mt-demo">
    <SelectRoot
      id="docs-multi-tags"
      v-model="selected"
      multiple
      :items="members"
      label-key="name"
      value-key="id"
    >
      <SelectControl v-slot="{ selectedItems, removeItem }" class="mt-control">
        <SelectTag
          v-for="item in selectedItems"
          :key="String(item.value)"
          :value="item.value"
          :label="item.label"
          class="mt-tag"
          @remove="removeItem"
        />
        <SelectInput placeholder="Add members..." class="mt-input" />
      </SelectControl>
      <SelectContent class="mt-content">
        <SelectOption
          v-for="member in members"
          :key="member.id"
          v-slot="{ selected: isSelected, active }"
          :value="member.id"
          :label="member.name"
          class="mt-option"
          :class="{
            'mt-option--selected': isSelected,
            'mt-option--active': active,
          }"
        >
          {{ member.name }}
        </SelectOption>
      </SelectContent>
    </SelectRoot>
    <p class="mt-hint">Press Backspace in an empty input to remove the last tag.</p>
    <p class="demo-note">This styling is for demos only. The library ships zero CSS</p>
  </div>
</template>

<style scoped>
.mt-demo {
  max-width: 400px;
}

.mt-control {
  display: flex;
  align-items: center;
  flex-wrap: wrap;
  gap: 4px;
  border: 1px solid var(--vp-c-divider);
  border-radius: 8px;
  padding: 0.375rem 0.5rem;
  background: var(--vp-c-bg);
  transition: border-color 0.2s;
  min-height: 40px;
}

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

.mt-tag {
  display: inline-flex;
  align-items: center;
  gap: 4px;
  padding: 0.125rem 0.375rem;
  background: var(--vp-c-brand-soft);
  border-radius: 4px;
  font-size: 0.8125rem;
  color: var(--vp-c-brand-1);
}

.mt-tag [data-part="remove"] {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  width: 16px;
  height: 16px;
  padding: 0;
  border: none;
  background: transparent;
  color: var(--vp-c-brand-1);
  cursor: pointer;
  border-radius: 2px;
  font-size: 0.75rem;
}

.mt-tag [data-part="remove"]:hover {
  background: var(--vp-c-brand-1);
  color: white;
}

.mt-input {
  flex: 1;
  min-width: 80px;
  border: none;
  outline: none;
  font-size: 0.9375rem;
  background: transparent;
  color: var(--vp-c-text-1);
  padding: 0.125rem 0.25rem;
}

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

.mt-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;
}

.mt-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;
}

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

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

.mt-hint {
  margin-top: 0.5rem;
  font-size: 0.8125rem;
  color: var(--vp-c-text-3);
}
</style>

How Tags Work

SelectControl exposes a scoped slot with selectedItems and removeItem:

<SelectControl v-slot="{ selectedItems, removeItem }">
  <SelectTag
    v-for="item in selectedItems"
    :key="String(item.value)"
    :value="item.value"
    :label="item.label"
    @remove="removeItem"
  />
  <SelectInput placeholder="Add members..." />
</SelectControl>

Slot Data	Type	Description
selectedItems	{ value: unknown; label: string }[]	Currently selected items with resolved labels
removeItem	(value: unknown) => void	Removes an item from the selection
multiple	boolean	Whether multi-select mode is active

SelectTag renders a tag with a remove button by default. You can customize it with a scoped slot:

<SelectTag :value="item.value" :label="item.label" v-slot="{ label, remove }">
  <span>{{ label }}</span>
  <button @click="remove">Remove</button>
</SelectTag>

Backspace removal: When the input is empty and the user presses Backspace, the last selected tag is automatically removed.

Max Selections with Hide Selected

Limit the number of selections with max and hide already-selected options from the dropdown with hide-selected (always enabled in this example).

Multi-Select with Max Limit and Hide Selected

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

const selected = ref<string[]>([])
const maxSelections = 3
const toppings = ['Pepper', 'Mushroom', 'Onion', 'Olive', 'Tomato']

const isAtMax = computed(() => selected.value.length >= maxSelections)
</script>

<template>
  <div class="mm-demo">
    <SelectRoot
      id="docs-multi-max"
      v-model="selected"
      multiple
      :max="maxSelections"
      hide-selected
    >
      <SelectControl v-slot="{ selectedItems, removeItem }" class="mm-control">
        <SelectTag
          v-for="item in selectedItems"
          :key="String(item.value)"
          :value="item.value"
          :label="item.label"
          class="mm-tag"
          @remove="removeItem"
        />
        <SelectInput
          :placeholder="isAtMax ? 'Max reached' : 'Pick up to 3 toppings...'"
          class="mm-input"
        />
        <SelectClear
          class="mm-clear"
          :class="{ 'mm-clear--hidden': selected.length === 0 }"
          @mousedown.prevent
        >
          Clear
        </SelectClear>
      </SelectControl>
      <SelectContent class="mm-content">
        <SelectOption
          v-for="topping in toppings"
          :key="topping"
          v-slot="{ active, disabled }"
          :value="topping"
          :label="topping"
          class="mm-option"
          :class="{
            'mm-option--active': active,
            'mm-option--disabled': disabled,
          }"
        >
          {{ topping }}
          <span v-if="disabled" class="mm-option-badge">limit reached</span>
        </SelectOption>
      </SelectContent>
    </SelectRoot>
    <p class="mm-status">
      {{ selected.length }}/{{ maxSelections }} selected
      <span v-if="isAtMax" class="mm-limit-note">(max reached)</span>
    </p>
    <p class="demo-note">This styling is for demos only. The library ships zero CSS</p>
  </div>
</template>

<style scoped>
.mm-demo {
  max-width: 400px;
}

.mm-control {
  display: flex;
  align-items: center;
  flex-wrap: nowrap;
  gap: 4px;
  border: 1px solid var(--vp-c-divider);
  border-radius: 8px;
  padding: 0.375rem 0.5rem;
  background: var(--vp-c-bg);
  transition: border-color 0.2s;
  min-height: 40px;
  overflow-x: auto;
}

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

.mm-tag {
  display: inline-flex;
  align-items: center;
  gap: 4px;
  padding: 0.125rem 0.375rem;
  background: var(--vp-c-brand-soft);
  border-radius: 4px;
  font-size: 0.8125rem;
  color: var(--vp-c-brand-1);
  flex: 0 0 auto;
  white-space: nowrap;
}

.mm-tag [data-part="remove"] {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  width: 16px;
  height: 16px;
  padding: 0;
  border: none;
  background: transparent;
  color: var(--vp-c-brand-1);
  cursor: pointer;
  border-radius: 2px;
  font-size: 0.75rem;
}

.mm-tag [data-part="remove"]:hover {
  background: var(--vp-c-brand-1);
  color: white;
}

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

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

.mm-clear {
  flex: 0 0 auto;
  padding: 0.25rem 0.5rem;
  border: 1px solid var(--vp-c-divider);
  border-radius: 4px;
  background: var(--vp-c-bg);
  color: var(--vp-c-text-3);
  font-size: 0.75rem;
  cursor: pointer;
  transition: color 0.15s, border-color 0.15s;
}

.mm-clear--hidden {
  visibility: hidden;
  pointer-events: none;
}

.mm-clear:hover {
  border-color: var(--vp-c-brand-1);
  color: var(--vp-c-brand-1);
}

.mm-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: 240px;
  overflow-y: auto;
  z-index: 50;
  padding: 4px;
}

.mm-option {
  display: flex;
  align-items: center;
  justify-content: space-between;
  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;
}

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

.mm-option--disabled {
  opacity: 0.5;
  cursor: not-allowed;
}

.mm-option-badge {
  font-size: 0.6875rem;
  color: var(--vp-c-text-3);
  font-style: italic;
}

.mm-status {
  margin-top: 0.75rem;
  font-size: 0.875rem;
  color: var(--vp-c-text-2);
}

.mm-limit-note {
  color: var(--vp-c-warning-1, #e5a200);
  font-weight: 500;
}
</style>

Props for Multi-Select Control

Prop	Type	Default	Description
multiple	boolean	false	Enable multi-select mode
max	number	undefined	Maximum number of selections allowed
hide-selected	boolean	false	Remove selected options from the visible dropdown

When the max limit is reached:

• Unselected options become disabled (grayed out, not clickable)
• The disabled scoped slot prop on SelectOption becomes true for unselected items
• Already-selected options can still be toggled off

Combine max with hide-selected for a cleaner experience. As users select options, those options disappear from the list, and the limit prevents selecting too many.

<SelectRoot v-model="selected" multiple :max="3" hide-selected>
  <!-- ... -->
</SelectRoot>

Next Steps

• Custom Filtering
• Basic Select
• Accessibility