# Introduction

Vue 3 Select Component is an accessible select for Vue 3. It focuses on developer experience, type safety, and ease of use.

## What is Vue 3 Select Component?

v1 has two APIs:

- **Assembled `Select`**: drop-in component with familiar DX from earlier versions.
- **Primitives**: composable building blocks (`SelectRoot`, `SelectTrigger`, `SelectPopover`, and more) for custom UX.

Both APIs share the same state machine, accessibility behavior, and TypeScript types.

## What you can do

- **Bind data with `v-model`**: single or multi-select with two-way binding
- **Search and filter options**: built-in search with custom filter logic
- **Customize rendering**: primitive slots for options, values, tags, icons, and empty states
- **Style your way**: default assembled styles with `--vs-*` variables, or unstyled primitives with `data-*` hooks
- **Teleport the menu**: render the dropdown anywhere in the DOM

## When to use it

Use the **assembled `Select`** for a production-ready select with sensible defaults. Good for migrations from `vue-select` or Vue 2.

Use **primitives** when you need custom UX like infinite scroll, custom positioning, or non-standard layouts.

::note
This documentation covers the v1 API. Still on v0? See the 

[v0 documentation](https://v0-vue3-select-component.vercel.app/){rel=""nofollow""}

. For upgrade steps, see the 

[migration guide](https://vue3-select-component.vercel.app/guide/migration)

.
::


# Installation

## Prerequisites

[Vue.js](https://vuejs.org){rel=""nofollow""} **3.5+** is required.

## Install the package

::code-group
```bash [pnpm]
pnpm add vue3-select-component
```

```bash [npm]
npm install vue3-select-component
```

```bash [yarn]
yarn add vue3-select-component
```

```bash [bun]
bun add vue3-select-component
```
::

## Import paths

v1 exposes two entry points:

| Import                             | Use case                                             |
| ---------------------------------- | ---------------------------------------------------- |
| `vue3-select-component`            | Assembled `Select` component (default export)        |
| `vue3-select-component/primitives` | Low-level primitive components                       |
| `vue3-select-component/styles`     | Default assembled Select styles (`--vs-*` variables) |
| `vue3-select-component/styles.css` | Same stylesheet (explicit `.css` subpath)            |

```ts
// Batteries-included
import Select from "vue3-select-component"
import "vue3-select-component/styles"

// Headless composition
import {
  SelectRoot,
  SelectTrigger,
  SelectValue,
  SelectPopover,
  SelectListbox,
  SelectOption,
} from "vue3-select-component/primitives"
```

## Styling

Import default styles for the assembled `Select`, then customize via `--vs-*` CSS variables (see [Styling](https://vue3-select-component.vercel.app/guide/styling)).

Primitives are headless. Use the default stylesheet or write your own CSS targeting `data-*` hooks.


# Usage

The assembled `Select` wires up all primitives with sensible defaults. It is the fastest way to get started.

## Use single select

Try the assembled `Select` in single-select mode:

::client-only
:usage-single-select-demo

#fallback
:select-demo-fallback
::

Import the component and bind `v-model` to your selected value:

```vue [App.vue]
<script setup lang="ts">
import { ref } from "vue"
import Select from "vue3-select-component"
import "vue3-select-component/styles"

const selected = ref<string | null>(null)
</script>

<template>
  <Select
    v-model="selected"
    :options="[
      { label: 'Option #1', value: 'option_1' },
      { label: 'Option #2', value: 'option_2' },
      { label: 'Option #3', value: 'option_3' },
    ]"
    placeholder="Select an option"
  />
</template>
```

Your IDE provides autocompletion and type checking automatically.

## Use multi-select

Try multi-select with the `multiple` prop:

::client-only
:usage-multi-select-demo

#fallback
:select-demo-fallback
::

Bind `v-model` to an array:

```vue [App.vue]
<script setup lang="ts">
import { ref } from "vue"
import Select from "vue3-select-component"
import "vue3-select-component/styles"

const selected = ref<string[]>([])
</script>

<template>
  <Select
    v-model="selected"
    multiple
    :options="[
      { label: 'Option #1', value: 'option_1' },
      { label: 'Option #2', value: 'option_2' },
      { label: 'Option #3', value: 'option_3' },
    ]"
  />
</template>
```

::note
Upgrading from v0? See the 

[migration guide](https://vue3-select-component.vercel.app/guide/migration)

. Props, events, and more have changed.
::

## Disable search or add clear

Search is enabled by default on the assembled `Select`. Disable it with `:searchable="false"` when you want a button-only select. Add `clearable` to show a clear button when a value is selected.

::client-only
:usage-clearable-demo

#fallback
:select-demo-fallback
::

```vue [App.vue]
<script setup lang="ts">
import { ref } from "vue"
import Select from "vue3-select-component"
import "vue3-select-component/styles"

const selected = ref<string | null>(null)

const options = [
  { label: "Option #1", value: "option_1" },
  { label: "Option #2", value: "option_2" },
  { label: "Option #3", value: "option_3" },
]
</script>

<template>
  <Select
    v-model="selected"
    :options="options"
    clearable
    placeholder="Search and select"
  />
</template>
```

## Bind data with v-model

The selected value stays reactive via Vue's `v-model`.

| Mode   | `v-model` type           | Default |
| ------ | ------------------------ | ------- |
| Single | `string | number | null` | `null`  |
| Multi  | `(string | number)[]`    | `[]`    |

[Learn more about `v-model`](https://vuejs.org/guide/components/v-model.html){rel="&#x22;nofollow&#x22;"}.

## Next steps

- [Browse examples](https://vue3-select-component.vercel.app/guide/examples) for clearable, loading, disabled options, and more
- [Read the assembled deep dive](https://vue3-select-component.vercel.app/guide/deep-dive) to see how primitives are wired together
- [Compose with primitives](https://vue3-select-component.vercel.app/guide/primitives) for full control
- [Configure options](https://vue3-select-component.vercel.app/guide/options) with custom shapes and mappers
- [Browse the API reference](https://vue3-select-component.vercel.app/api/props) for all props and events


# Primitives

Primitives are headless building blocks that share state via `SelectRoot`. Each one handles a single concern like trigger, popover, or listbox.

## Understand the architecture

```text
SelectRoot (state + context provider)
├── SelectTrigger
│   ├── SelectIcon
│   ├── SelectValue
│   ├── SelectInput (when searchable)
│   ├── SelectTrailingIcon
│   └── SelectClear
└── SelectPopover
    └── SelectListbox
        ├── SelectNoOptions
        └── SelectOption (×N)
            └── optional: SelectGroup, SelectGroupLabel, SelectSeparator
```

Cross-component state uses provide/inject. Primitives must live inside `SelectRoot`. Group primitives are optional. Use them only when you need labelled sections or separators in the list.

## Build a searchable single select

```vue [CustomSelect.vue]
<script setup lang="ts">
import { ref } from "vue"
import {
  SelectRoot,
  SelectTrigger,
  SelectValue,
  SelectIcon,
  SelectTrailingIcon,
  SelectClear,
  SelectPopover,
  SelectInput,
  SelectListbox,
  SelectOption,
  SelectNoOptions,
} from "vue3-select-component/primitives"
import "vue3-select-component/styles"

const options = [
  { value: "js", label: "JavaScript" },
  { value: "ts", label: "TypeScript" },
]

const model = ref<string | null>(null)
</script>

<template>
  <div data-assembled-select>
    <SelectRoot v-model="model" :options="options" searchable clearable>
      <SelectTrigger>
        <SelectIcon>
          <UIcon name="i-lucide-code" />
        </SelectIcon>
        <SelectValue placeholder="Pick a language" />
        <SelectInput />
        <SelectTrailingIcon />
        <SelectClear />
      </SelectTrigger>

      <SelectPopover>
        <SelectListbox>
          <SelectNoOptions>No results</SelectNoOptions>
          <SelectOption
            v-for="opt in options"
            :key="opt.value"
            :value="opt.value"
            :label="opt.label"
          />
        </SelectListbox>
      </SelectPopover>
    </SelectRoot>
  </div>
</template>
```

## Register options two ways

**Via `options` prop on `SelectRoot`**: pass a normalized array:

```ts
{ label: string; value: string | number; disabled?: boolean }[]
```

**Via declarative `SelectOption` children**: register options on mount. Both sources merge. Declarative options are skipped when their `value` already exists from the prop.

## Group options

::note
You do not need group primitives for a flat list. Render 

`SelectOption`

 children directly inside 

`SelectListbox`

, as in the example above.
::

Reach for `SelectGroup`, `SelectGroupLabel`, and `SelectSeparator` only when options belong in labelled sections or need visual dividers. Groups and separators are not selectable and do not change keyboard navigation.

```vue [CustomSelect.vue]
<script setup lang="ts">
import { ref } from "vue"
import {
  SelectGroup,
  SelectGroupLabel,
  SelectInput,
  SelectListbox,
  SelectOption,
  SelectPopover,
  SelectRoot,
  SelectSeparator,
  SelectTrailingIcon,
  SelectTrigger,
  SelectValue,
} from "vue3-select-component/primitives"
import "vue3-select-component/styles"

const model = ref<string | null>(null)
</script>

<template>
  <SelectRoot v-model="model" searchable>
    <SelectTrigger>
      <SelectValue placeholder="Pick a technology" />
      <SelectInput />
      <SelectTrailingIcon />
    </SelectTrigger>

    <SelectPopover>
      <SelectListbox>
        <SelectGroup>
          <SelectGroupLabel>Frontend</SelectGroupLabel>
          <SelectOption value="vue" label="Vue" />
          <SelectOption value="react" label="React" />
        </SelectGroup>

        <SelectSeparator />

        <SelectGroup>
          <SelectGroupLabel>Backend</SelectGroupLabel>
          <SelectOption value="node" label="Node.js" />
          <SelectOption value="rust" label="Rust" />
        </SelectGroup>
      </SelectListbox>
    </SelectPopover>
  </SelectRoot>
</template>
```

Grouped options still register as normal options. When filtering hides every option in a group, the group label is hidden too.

## Teleport the popover

`SelectPopover` teleports to `document.body` by default so the dropdown escapes overflow and stacking-context constraints. Scoped styles from parent components still apply to slot content after teleport.

Disable teleport or target a custom container with the `teleport` prop:

```vue
<!-- default: teleports to document.body -->
<SelectPopover>
  <SelectListbox />
</SelectPopover>

<SelectPopover teleport="#menu-portal">
  <!-- custom portal target -->
</SelectPopover>

<SelectPopover :teleport="false">
  <!-- render inline -->
</SelectPopover>
```

## Popover behavior

`SelectPopover` wraps reka-ui `Popover`. Pass reka-ui popover props to control placement, collision behavior, modality, and portal deferral:

```vue
<SelectPopover
  side="top"
  :side-offset="8"
  align="end"
  :collision-padding="16"
>
  <SelectListbox />
</SelectPopover>
```

The assembled `Select` accepts the same props and forwards them to `SelectPopover`. See [Popover props](https://vue3-select-component.vercel.app/api/props#popover-props) for the full list.

## Customize with slots

Primitives expose slots for rendering. See [Slots](https://vue3-select-component.vercel.app/api/slots) for the full reference.

| Primitive            | Slot                | Purpose                            |
| -------------------- | ------------------- | ---------------------------------- |
| `SelectValue`        | `default`           | Custom single/multi value display  |
| `SelectOption`       | `default`           | Custom option content              |
| `SelectGroup`        | `default`           | Group related options              |
| `SelectGroupLabel`   | `default`           | Label a group for assistive tech   |
| `SelectTag`          | `default`, `remove` | Custom multi-value tags            |
| `SelectIcon`         | `default`           | Leading icon before the value      |
| `SelectTrailingIcon` | `default`           | Custom trailing icon or loading UI |
| `SelectNoOptions`    | `default`           | Custom empty state                 |

## When to use primitives vs assembled Select

| Use assembled `Select` | Use primitives                           |
| ---------------------- | ---------------------------------------- |
| Standard dropdown UX   | Custom layouts or infinite scroll        |
| Quick integration      | Non-standard trigger or popover behavior |
| Migrating from v0      | Full control over every DOM node         |

See the [components reference](https://vue3-select-component.vercel.app/api/components) for props and behavior of each primitive.

For how assembled `Select` wires these primitives together, see [Assembled Select deep dive](https://vue3-select-component.vercel.app/guide/deep-dive).


# Complex use cases

These recipes combine primitives with external libraries or custom list rendering. They assume you are comfortable composing `SelectRoot` yourself.

## Virtualized list

Register a large option set on `SelectRoot`, then render only visible rows inside `SelectListbox`. Keyboard navigation and search still run against the full list.

This demo registers 50,000 options and mounts roughly a dozen DOM rows at a time with [VueUse `useVirtualList`](https://vueuse.org/core/useVirtualList/){rel="&#x22;nofollow&#x22;"}.

::client-only
:example-virtualized-primitives-demo

#fallback
:select-demo-fallback
::

Install [`@vueuse/core`](https://vueuse.org/){rel="&#x22;nofollow&#x22;"} alongside the select package:

::code-group
```bash [pnpm]
pnpm add vue3-select-component @vueuse/core
```

```bash [npm]
npm install vue3-select-component @vueuse/core
```

```bash [yarn]
yarn add vue3-select-component @vueuse/core
```

```bash [bun]
bun add vue3-select-component @vueuse/core
```
::

The example splits into two files:

- Parent select that registers every option `VirtualizedSelect.vue`
- Virtual list child that reads `filteredOptions` from context `VirtualizedOptionList.vue`

::code-group
```vue [VirtualizedSelect.vue]
<script setup lang="ts">
import type { SelectOptionData } from "vue3-select-component"

import { ref } from "vue"
import {
  SelectInput,
  SelectListbox,
  SelectPopover,
  SelectRoot,
  SelectTrailingIcon,
  SelectTrigger,
  SelectValue,
} from "vue3-select-component/primitives"
import "vue3-select-component/styles"

import VirtualizedOptionList from "./VirtualizedOptionList.vue"

const OPTION_COUNT = 50_000

const allOptions: SelectOptionData[] = Array.from(
  { length: OPTION_COUNT },
  (_, index) => {
    const id = index + 1

    return {
      label: `Option ${id.toLocaleString()}`,
      value: String(id),
    }
  },
)

const selected = ref<string | null>(null)
</script>

<template>
  <div data-assembled-select>
    <SelectRoot
      v-model="selected"
      :options="allOptions"
      searchable
    >
      <SelectTrigger>
        <SelectValue placeholder="Pick from 50,000 options" />
        <SelectInput />
        <SelectTrailingIcon />
      </SelectTrigger>

      <SelectPopover :teleport="false">
        <SelectListbox class="virtualized-listbox">
          <VirtualizedOptionList :total-count="OPTION_COUNT" />
        </SelectListbox>
      </SelectPopover>
    </SelectRoot>
  </div>
</template>

<style scoped>
:deep([data-select-listbox].virtualized-listbox) {
  overflow: hidden;
}
</style>
```

```vue [VirtualizedOptionList.vue]
<script setup lang="ts">
import { computed, watch } from "vue"
import { useVirtualList } from "@vueuse/core"
import {
  injectSelectContext,
  SelectNoOptions,
  SelectOption,
} from "vue3-select-component/primitives"

const OPTION_ROW_HEIGHT = 40

defineProps<{
  totalCount: number
}>()

const context = injectSelectContext()

const filteredOptions = computed(() => [...context.filteredOptions.value])

const { list, containerProps, wrapperProps, scrollTo } = useVirtualList(
  filteredOptions,
  {
    itemHeight: OPTION_ROW_HEIGHT,
    overscan: 8,
  },
)

watch(
  () => context.activeOptionValue.value,
  (activeValue) => {
    if (activeValue == null) {
      return
    }

    const activeIndex = filteredOptions.value.findIndex(
      (option) => option.value === activeValue,
    )

    if (activeIndex >= 0) {
      scrollTo(activeIndex)
    }
  },
)
</script>

<template>
  <SelectNoOptions />

  <div
    class="virtualized-option-list"
    v-bind="containerProps"
  >
    <div v-bind="wrapperProps">
      <SelectOption
        v-for="item in list"
        :key="String(item.data.value)"
        :value="item.data.value"
        :label="item.data.label"
        :disabled="item.data.disabled"
        class="virtualized-option-list__row"
      />
    </div>
  </div>

  <p class="virtualized-option-list__stats">
    {{ totalCount.toLocaleString() }} options registered.
    {{ list.length }} rows mounted in the DOM.
  </p>
</template>

<style scoped>
.virtualized-option-list {
  height: var(--vs-menu-height, 200px);
  overflow: auto;
}

.virtualized-option-list__row {
  height: 40px;
  box-sizing: border-box;
}

.virtualized-option-list__stats {
  margin: 0.75rem 0 0;
  padding: 0 0.75rem 0.75rem;
  font-size: 0.8125rem;
  color: #71717a;
}
</style>
```
::

::note
Pass every option to 

`SelectRoot`

 through 

`:options`

 so filtering and keyboard navigation stay in sync. Set 

`:teleport="false"`

 on 

`SelectPopover`

 when the virtual list owns scrolling. Keep a fixed row height on each 

`SelectOption`

 so 

`useVirtualList`

 can measure correctly. Watch 

`activeOptionValue`

 and call 

`scrollTo`

 so keyboard focus keeps the active row visible.
::

## Infinite scroll

Load options in pages as the user scrolls the menu. This demo fetches [JSONPlaceholder](https://jsonplaceholder.typicode.com/guide/){rel="&#x22;nofollow&#x22;"} posts with `_start` and `_limit`, then appends each page to `:options`.

::client-only
:example-infinite-scroll-primitives-demo

#fallback
:select-demo-fallback
::

Install [`@vueuse/core`](https://vueuse.org/){rel="&#x22;nofollow&#x22;"} alongside the select package:

::code-group
```bash [pnpm]
pnpm add vue3-select-component @vueuse/core
```

```bash [npm]
npm install vue3-select-component @vueuse/core
```

```bash [yarn]
yarn add vue3-select-component @vueuse/core
```

```bash [bun]
bun add vue3-select-component @vueuse/core
```
::

The parent owns fetch state. A child list component attaches [`useInfiniteScroll`](https://vueuse.org/core/useInfiniteScroll/){rel="&#x22;nofollow&#x22;"} to a scroll container inside `SelectListbox`.

::code-group
```vue [InfiniteScrollSelect.vue]
<script setup lang="ts">
import type { SelectOptionData } from "vue3-select-component"

import { computed, ref } from "vue"
import {
  SelectListbox,
  SelectPopover,
  SelectRoot,
  SelectTrailingIcon,
  SelectTrigger,
  SelectValue,
} from "vue3-select-component/primitives"
import "vue3-select-component/styles"

import InfiniteScrollOptionList from "./InfiniteScrollOptionList.vue"
import { fetchPostsPage, postToSelectOption } from "./jsonplaceholder"

const PAGE_SIZE = 20

const selected = ref<number | null>(null)
const options = ref<SelectOptionData<number>[]>([])
const totalCount = ref(0)
const isLoading = ref(false)
const isLoadingMore = ref(false)

const hasMore = computed(() => options.value.length < totalCount.value)

async function loadPosts(append: boolean) {
  if (append) {
    if (!hasMore.value || isLoadingMore.value) {
      return
    }

    isLoadingMore.value = true
  }
  else {
    isLoading.value = true
  }

  const { posts, total } = await fetchPostsPage({
    start: append ? options.value.length : 0,
    limit: PAGE_SIZE,
  })

  totalCount.value = total
  const nextOptions = posts.map(postToSelectOption)
  options.value = append ? [...options.value, ...nextOptions] : nextOptions
  isLoading.value = false
  isLoadingMore.value = false
}

function onMenuOpened() {
  if (options.value.length === 0) {
    loadPosts(false)
  }
}
</script>

<template>
  <div data-assembled-select>
    <SelectRoot
      v-model="selected"
      :options="options"
      :loading="isLoading"
      @menu-opened="onMenuOpened"
    >
      <SelectTrigger>
        <SelectValue placeholder="Pick a post" />
        <SelectTrailingIcon />
      </SelectTrigger>

      <SelectPopover>
        <SelectListbox class="infinite-scroll-listbox">
          <InfiniteScrollOptionList
            :loaded-count="options.length"
            :total-count="totalCount"
            :is-loading-more="isLoadingMore"
            :has-more="hasMore"
            @load-more="loadPosts(true)"
          />
        </SelectListbox>
      </SelectPopover>
    </SelectRoot>
  </div>
</template>

<style scoped>
:deep([data-select-listbox].infinite-scroll-listbox) {
  overflow: hidden;
}
</style>
```

```vue [InfiniteScrollOptionList.vue]
<script setup lang="ts">
import { computed, useTemplateRef } from "vue"
import { useInfiniteScroll } from "@vueuse/core"
import {
  injectSelectContext,
  SelectNoOptions,
  SelectOption,
} from "vue3-select-component/primitives"

const props = defineProps<{
  loadedCount: number
  totalCount: number
  isLoadingMore: boolean
  hasMore: boolean
}>()

const emit = defineEmits<{
  loadMore: []
}>()

const context = injectSelectContext<number>()
const scrollContainer = useTemplateRef("scrollContainer")
const filteredOptions = computed(() => [...context.filteredOptions.value])

useInfiniteScroll(
  scrollContainer,
  () => emit("loadMore"),
  {
    distance: 48,
    canLoadMore: () => props.hasMore && !props.isLoadingMore,
  },
)
</script>

<template>
  <SelectNoOptions />

  <div ref="scrollContainer" class="infinite-scroll-option-list">
    <SelectOption
      v-for="option in filteredOptions"
      :key="String(option.value)"
      :value="option.value"
      :label="option.label"
    />

    <p v-if="isLoadingMore" role="status">Loading more…</p>
  </div>

  <p class="infinite-scroll-option-list__stats">
    {{ loadedCount }} of {{ totalCount }} posts loaded.
  </p>
</template>

<style scoped>
.infinite-scroll-option-list {
  height: var(--vs-menu-height, 200px);
  overflow: auto;
}
</style>
```

```ts [jsonplaceholder.ts]
const POSTS_URL = "https://jsonplaceholder.typicode.com/posts"

export async function fetchPostsPage(params: { start: number; limit: number }) {
  const url = new URL(POSTS_URL)
  url.searchParams.set("_start", String(params.start))
  url.searchParams.set("_limit", String(params.limit))

  const response = await fetch(url)
  const total = Number(response.headers.get("X-Total-Count") ?? 0)
  const posts = await response.json()

  return { posts, total }
}

export function postToSelectOption(post: { id: number; title: string }) {
  return { label: post.title, value: post.id }
}
```
::

::note
Register every loaded page on 

`:options`

 so keyboard navigation stays correct. Set the listbox overflow to 

`hidden`

 and scroll inside a child container so 

`useInfiniteScroll`

 can attach to a ref you control. Use 

`:loading`

 for the first fetch and a footer row for later pages.
::

## Remote search

Query a remote API when the user types. This demo debounces `@search` and calls JSONPlaceholder with the `title_like` filter param.

::client-only
:example-remote-search-primitives-demo

#fallback
:select-demo-fallback
::

::code-group
```vue [RemoteSearchSelect.vue]
<script setup lang="ts">
import type { SelectOptionData } from "vue3-select-component"

import { ref } from "vue"
import { useDebounceFn } from "@vueuse/core"
import {
  SelectInput,
  SelectListbox,
  SelectNoOptions,
  SelectOption,
  SelectPopover,
  SelectRoot,
  SelectTrailingIcon,
  SelectTrigger,
  SelectValue,
} from "vue3-select-component/primitives"
import "vue3-select-component/styles"

import { postToSelectOption, searchPosts } from "./jsonplaceholder"

const selected = ref<number | null>(null)
const options = ref<SelectOptionData<number>[]>([])
const isLoading = ref(false)

let activeRequestId = 0

function passThroughFilter() {
  return true
}

async function fetchRemoteOptions(query: string) {
  const requestId = ++activeRequestId
  isLoading.value = true

  const posts = await searchPosts({ query })

  if (requestId !== activeRequestId) {
    return
  }

  options.value = posts.map(postToSelectOption)
  isLoading.value = false
}

const onSearchDebounced = useDebounceFn(fetchRemoteOptions, 300)

function onMenuOpened() {
  if (options.value.length === 0) {
    fetchRemoteOptions("")
  }
}
</script>

<template>
  <div data-assembled-select>
    <SelectRoot
      v-model="selected"
      :options="options"
      searchable
      :loading="isLoading"
      :filter-by="passThroughFilter"
      @search="onSearchDebounced"
      @menu-opened="onMenuOpened"
    >
      <SelectTrigger>
        <SelectValue placeholder="Search posts by title" />
        <SelectInput />
        <SelectTrailingIcon />
      </SelectTrigger>

      <SelectPopover>
        <SelectListbox>
          <SelectNoOptions>
            <template #default="{ searchValue }">
              {{ isLoading ? "Searching…" : `No posts match "${searchValue}"` }}
            </template>
          </SelectNoOptions>

          <SelectOption
            v-for="option in options"
            :key="String(option.value)"
            :value="option.value"
            :label="option.label"
          />
        </SelectListbox>
      </SelectPopover>
    </SelectRoot>
  </div>
</template>
```

```ts [jsonplaceholder.ts]
const POSTS_URL = "https://jsonplaceholder.typicode.com/posts"

export async function searchPosts(params: { query: string; limit?: number }) {
  const url = new URL(POSTS_URL)

  if (params.query.trim()) {
    url.searchParams.set("title_like", params.query.trim())
  }

  url.searchParams.set("_limit", String(params.limit ?? 50))

  const response = await fetch(url)

  return response.json()
}

export function postToSelectOption(post: { id: number; title: string }) {
  return { label: post.title, value: post.id }
}
```
::

::note
Set 

`:filter-by`

 to pass through server results. Without it, the built-in label filter hides options that do not match the typed string locally. Track a request id or use 

`AbortController`

 to ignore stale responses when search changes quickly.
::

## Next steps

- [Primitives guide](https://vue3-select-component.vercel.app/guide/primitives) for the full composition model
- [Examples](https://vue3-select-component.vercel.app/guide/examples) for smaller building blocks
- [Deep dive](https://vue3-select-component.vercel.app/guide/deep-dive) for how context and option registration work


# Nuxt

Vue 3 Select Component works in Nuxt 3 and 4. No dedicated module is required.

## Install

Install the package as usual. See [Installation](https://vue3-select-component.vercel.app/getting-started/installation).

## Import styles

Import the stylesheet once in `nuxt.config.ts`:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  css: ["vue3-select-component/styles"],
})
```

## Use in pages and components

Bind `v-model` the same way as in a Vite SPA:

```vue [pages/index.vue]
<script setup lang="ts">
import { ref } from "vue"
import Select from "vue3-select-component"

const selected = ref<string | null>(null)

const options = [
  { label: "Option #1", value: "option_1" },
  { label: "Option #2", value: "option_2" },
]
</script>

<template>
  <Select
    v-model="selected"
    :options="options"
    placeholder="Select an option"
  />
</template>
```

Primitives work the same way. Import from `vue3-select-component/primitives`.

## SSR and SSG caveats

The select teleports its dropdown to `document.body` by default. That portal is not present during server render and can cause hydration warnings.

Pick one approach:

### `ClientOnly` (recommended)

Wrap the component with [`ClientOnly`](https://nuxt.com/docs/4.x/api/components/client-only){rel="&#x22;nofollow&#x22;"} for the simplest fix.

The control renders on the client only, once hydration is complete. Add a `#fallback` slot if you want to avoid layout shift.

```vue [pages/index.vue]
<template>
  <ClientOnly fallback="Loading...">
    <Select v-model="selected" :options="options" />
  </ClientOnly>
</template>
```

::note
This is what we use to write interactive docs demos in this project.
::

### Disable teleport

Pass `:teleport="false"` to keep the dropdown in the component tree. The closed trigger hydrates without a portal mismatch. Use this when you need the control in static HTML or inside overflow containers you control.

```vue [pages/index.vue]
<Select
  v-model="selected"
  :options="options"
  :teleport="false"
/>
```

With primitives, set `teleport` on `SelectPopover`.

### Defer portal

Pass `defer` on `Select` or `SelectPopover` to delay teleport until after mount. Keeps default body teleport without wrapping the whole control.

Learn more about [deferred teleports](https://vuejs.org/guide/built-ins/teleport.html#deferred-teleport){rel="&#x22;nofollow&#x22;"} and [on Reka-UI popover portal docs](https://reka-ui.com/docs/components/popover#portal){rel="&#x22;nofollow&#x22;"}.

## Static generation

`nuxt generate` follows the same rules. Use `ClientOnly`, `:teleport="false"`, or `defer` on every page that renders a select. Search and keyboard behavior run after client hydration.

::note
Form attributes (

`name`

, 

`id`

, 

`required`

, and ARIA props) pass through to the trigger. They work in SSR markup when the control itself is server-rendered.
::


# Options

The `options` prop populates the dropdown menu.

## Use the basic structure

Each option needs a `label` and a `value`:

```vue [App.vue]
<script setup lang="ts">
import { ref } from "vue"
import Select from "vue3-select-component"
import "vue3-select-component/styles"

const selected = ref<string | null>(null)
</script>

<template>
  <Select
    v-model="selected"
    :options="[
      { label: 'JavaScript', value: 'js' },
      { label: 'TypeScript', value: 'ts' },
    ]"
    placeholder="Pick a language"
  />
</template>
```

| Property | Description                                                  |
| -------- | ------------------------------------------------------------ |
| `label`  | Text shown in the dropdown and selected value                |
| `value`  | Data bound to `v-model` when selected (`string` or `number`) |

::note
Import the `SelectOption` type (exported as `SelectOptionData`) for TypeScript:

```ts
import type { SelectOptionData } from "vue3-select-component"

const options: SelectOptionData<string>[] = [
  { label: "JavaScript", value: "js" },
]
```
::

## Disable individual options

Add `disabled: true` to prevent selection:

```vue [App.vue]
<script setup lang="ts">
import { ref } from "vue"
import Select from "vue3-select-component"
import "vue3-select-component/styles"

const selected = ref<string | null>(null)
</script>

<template>
  <Select
    v-model="selected"
    :options="[
      { label: 'Available', value: 'a1' },
      { label: 'Unavailable', value: 'a2', disabled: true },
    ]"
    placeholder="Pick an option"
  />
</template>
```

Disabled options cannot be selected. They are skipped during keyboard navigation and get `aria-disabled`.

## Use custom option shapes

When your data does not match `{ label, value }`, provide mappers:

```vue [App.vue]
<script setup lang="ts">
import { ref } from "vue"
import Select from "vue3-select-component"
import "vue3-select-component/styles"

type Country = { id: string; key: string }

const countries: Country[] = [
  { id: "France", key: "fr" },
  { id: "Germany", key: "de" },
]

const selected = ref<string | null>(null)
</script>

<template>
  <Select
    v-model="selected"
    :options="countries"
    :get-option-label="(o) => o.id"
    :get-option-value="(o) => o.key"
    placeholder="Select a country"
  />
</template>
```

| Prop             | Type                          | Default        |
| ---------------- | ----------------------------- | -------------- |
| `getOptionLabel` | `(option) => string`          | `option.label` |
| `getOptionValue` | `(option) => string | number` | `option.value` |

## Customize search filtering

By default, search matches case-insensitive substrings on the option label.

**Assembled `Select`**: filter receives the source option object:

```ts
type GenericFilterByFn<GenericOption> = (
  option: GenericOption,
  label: string,
  search: string,
) => boolean
```

```vue [App.vue]
<script setup lang="ts">
import { ref } from "vue"
import Select from "vue3-select-component"
import "vue3-select-component/styles"

type CountryOption = {
  label: string
  value: string
  code: string
}

const selected = ref<string | null>(null)

const options: CountryOption[] = [
  { label: "France", value: "FR", code: "fr" },
  { label: "Germany", value: "DE", code: "de" },
]
</script>

<template>
  <Select
    v-model="selected"
    :options="options"
    :filter-by="(option, label, search) =>
      label.toLowerCase().includes(search.toLowerCase())
      || option.code.toLowerCase().includes(search.toLowerCase())"
    placeholder="Search by name or code"
  />
</template>
```

**Primitives (`SelectRoot`)**: filter receives the registered option:

```ts
type FilterByFn<Value> = (
  option: RegisteredOption<Value>,
  search: string,
) => boolean
```

## Add extended properties

Options can carry extra fields for custom rendering via primitive slots:

```vue [CustomSelect.vue]
<script setup lang="ts">
import { ref } from "vue"
import {
  SelectInput,
  SelectListbox,
  SelectNoOptions,
  SelectOption,
  SelectPopover,
  SelectRoot,
  SelectTrailingIcon,
  SelectTrigger,
  SelectValue,
} from "vue3-select-component/primitives"
import "vue3-select-component/styles"

type LanguageOption = {
  label: string
  value: string
  version: string
  creator: string
}

const selected = ref<string | null>(null)

const options: LanguageOption[] = [
  { label: "JavaScript", value: "js", version: "ES2022", creator: "Brendan Eich" },
  { label: "TypeScript", value: "ts", version: "5.0", creator: "Microsoft" },
]
</script>

<template>
  <div data-assembled-select>
    <SelectRoot v-model="selected" :options="options" searchable>
      <SelectTrigger>
        <SelectValue placeholder="Pick a language" />
        <SelectInput />
        <SelectTrailingIcon />
      </SelectTrigger>

      <SelectPopover>
        <SelectListbox>
          <SelectNoOptions />
          <SelectOption
            v-for="option in options"
            :key="option.value"
            :value="option.value"
            :label="option.label"
          >
            <span>{{ option.label }} ({{ option.version }})</span>
            <span>{{ option.creator }}</span>
          </SelectOption>
        </SelectListbox>
      </SelectPopover>
    </SelectRoot>
  </div>
</template>
```

See [TypeScript](https://vue3-select-component.vercel.app/guide/typescript) for extending option types safely.


# Multi-select

Multi-select lets users pick more than one option. Enable it with the `multiple` prop on assembled `Select` or `SelectRoot`.

## Enable multi-select

```vue [App.vue]
<script setup lang="ts">
import { ref } from "vue"
import Select from "vue3-select-component"
import "vue3-select-component/styles"

const selected = ref<string[]>([])
</script>

<template>
  <Select
    v-model="selected"
    multiple
    :options="[
      { label: 'JavaScript', value: 'js' },
      { label: 'TypeScript', value: 'ts' },
      { label: 'Vue', value: 'vue' },
    ]"
    placeholder="Select languages"
  />
</template>
```

## Understand model behavior

| Aspect         | Behavior                                       |
| -------------- | ---------------------------------------------- |
| `v-model` type | `(string | number)[]`                          |
| Default value  | `[]`                                           |
| Selecting      | Adds value to the array. Menu stays open.      |
| Deselecting    | Click a selected option to toggle it off       |
| Clear button   | Resets to `[]`, emits `optionDeselected(null)` |

## Selected option checkmarks

In multi-select mode, selected options in the dropdown show a checkmark on the right. The assembled `Select` and primitive `SelectOption` render this by default. Override it with the `checkmark` slot on `SelectOption`.

```vue [CustomSelect.vue]
<script setup lang="ts">
import { ref } from "vue"
import {
  SelectInput,
  SelectListbox,
  SelectNoOptions,
  SelectOption,
  SelectPopover,
  SelectRoot,
  SelectTrailingIcon,
  SelectTrigger,
  SelectValue,
} from "vue3-select-component/primitives"
import "vue3-select-component/styles"

const selected = ref<string[]>([])

const options = [
  { label: "JavaScript", value: "js" },
  { label: "TypeScript", value: "ts" },
  { label: "Vue", value: "vue" },
]
</script>

<template>
  <div data-assembled-select>
    <SelectRoot v-model="selected" multiple searchable>
      <SelectTrigger>
        <SelectValue placeholder="Pick languages" />
        <SelectInput />
        <SelectTrailingIcon />
      </SelectTrigger>

      <SelectPopover>
        <SelectListbox>
          <SelectNoOptions />
          <SelectOption
            v-for="opt in options"
            :key="opt.value"
            :value="opt.value"
            :label="opt.label"
          >
            <template #checkmark>
              <UIcon name="i-lucide-check" />
            </template>
          </SelectOption>
        </SelectListbox>
      </SelectPopover>
    </SelectRoot>
  </div>
</template>
```

Style the layout with `data-select-option-label` and `data-select-option-checkmark`.

## Hide selected options

By default, selected options stay visible in the dropdown so users can deselect them. Set `hide-selected` on assembled `Select` to remove them from the list:

```vue [App.vue]
<script setup lang="ts">
import { ref } from "vue"
import Select from "vue3-select-component"
import "vue3-select-component/styles"

const selected = ref<string[]>(["js"])

const options = [
  { label: "JavaScript", value: "js" },
  { label: "TypeScript", value: "ts" },
  { label: "Vue", value: "vue" },
]
</script>

<template>
  <Select
    v-model="selected"
    multiple
    hide-selected
    :options="options"
    placeholder="Select languages"
  />
</template>
```

On primitives, pass `hide-selected` to `SelectRoot`:

```vue [CustomSelect.vue]
<script setup lang="ts">
import { ref } from "vue"
import {
  SelectInput,
  SelectListbox,
  SelectNoOptions,
  SelectOption,
  SelectPopover,
  SelectRoot,
  SelectTrailingIcon,
  SelectTrigger,
  SelectValue,
} from "vue3-select-component/primitives"
import "vue3-select-component/styles"

const model = ref<string[]>([])

const options = [
  { label: "JavaScript", value: "js" },
  { label: "TypeScript", value: "ts" },
  { label: "Vue", value: "vue" },
]
</script>

<template>
  <div data-assembled-select>
    <SelectRoot v-model="model" multiple hide-selected :options="options" searchable>
      <SelectTrigger>
        <SelectValue placeholder="Select languages" />
        <SelectInput />
        <SelectTrailingIcon />
      </SelectTrigger>

      <SelectPopover>
        <SelectListbox>
          <SelectNoOptions />
          <SelectOption
            v-for="option in options"
            :key="option.value"
            :value="option.value"
            :label="option.label"
          />
        </SelectListbox>
      </SelectPopover>
    </SelectRoot>
  </div>
</template>
```

## Customize tag remove icon

In multi-select mode, each tag shows a remove button. Override the icon on the assembled `Select` with the `tag-remove` slot:

```vue [App.vue]
<script setup lang="ts">
import { ref } from "vue"
import Select from "vue3-select-component"
import "vue3-select-component/styles"

const selected = ref<string[]>(["js"])

const options = [
  { label: "JavaScript", value: "js" },
  { label: "TypeScript", value: "ts" },
  { label: "Vue", value: "vue" },
]
</script>

<template>
  <Select v-model="selected" multiple :options="options">
    <template #tag-remove>
      <UIcon name="i-lucide-x" />
    </template>
  </Select>
</template>
```

The slot receives `{ label, value }` for each tag. On primitives, use the `remove` slot on `SelectTag` or forward it from `SelectValue` with `tag-remove`.

## Display selected values

By default, `SelectValue` renders a `SelectTag` for each selection. Customize tags with primitive slots:

```vue [CustomSelect.vue]
<script setup lang="ts">
import { ref } from "vue"
import {
  SelectInput,
  SelectListbox,
  SelectNoOptions,
  SelectOption,
  SelectPopover,
  SelectRoot,
  SelectTag,
  SelectTrailingIcon,
  SelectTrigger,
  SelectValue,
} from "vue3-select-component/primitives"
import "vue3-select-component/styles"

const model = ref<string[]>([])

const options = [
  { label: "JavaScript", value: "js" },
  { label: "TypeScript", value: "ts" },
  { label: "Vue", value: "vue" },
]
</script>

<template>
  <div data-assembled-select>
    <SelectRoot v-model="model" multiple :options="options" searchable>
      <SelectTrigger>
        <SelectValue placeholder="Pick languages">
          <template #default="{ selectedOptions }">
            <SelectTag
              v-for="opt in selectedOptions"
              :key="String(opt.value)"
              :value="opt.value"
              :label="opt.label"
            >
              <template #default="{ label }">
                <strong>{{ label }}</strong>
              </template>
            </SelectTag>
          </template>
        </SelectValue>
        <SelectInput />
        <SelectTrailingIcon />
      </SelectTrigger>

      <SelectPopover>
        <SelectListbox>
          <SelectNoOptions />
          <SelectOption
            v-for="option in options"
            :key="option.value"
            :value="option.value"
            :label="option.label"
          />
        </SelectListbox>
      </SelectPopover>
    </SelectRoot>
  </div>
</template>
```

## Remove values with keyboard

When the menu is open, searchable, and the search field is empty, **Backspace** removes the last selected tag. This updates `v-model` without emitting `optionDeselected`.

## Combine with search and clear

```vue [App.vue]
<script setup lang="ts">
import { ref } from "vue"
import Select from "vue3-select-component"
import "vue3-select-component/styles"

const selected = ref<string[]>([])

const options = [
  { label: "JavaScript", value: "js" },
  { label: "TypeScript", value: "ts" },
  { label: "Vue", value: "vue" },
]
</script>

<template>
  <Select
    v-model="selected"
    multiple
    clearable
    :options="options"
    placeholder="Search and select languages"
  />
</template>
```

- **Search** filters visible options without affecting selected values
- **Clear** removes all selections at once


# Styling

## Default styles for assembled Select

The assembled `Select` ships optional default styles. Import them once in your app entry:

```ts
import "vue3-select-component/styles"
```

Primitives remain **unstyled** unless you import the stylesheet and target their `data-*` hooks yourself.

::note
Styles are not auto-injected (CSP-friendly). Import them manually, as in v0.
::

## CSS variables

Default styles use `--vs-*` variables (same prefix as v0). They are defined on `:root`, `[data-assembled-select]`, and `[data-select-popover]` so teleported dropdown panels inherit your theme.

Override variables on the assembled select root:

```vue [App.vue]
<script setup lang="ts">
import { ref } from "vue"
import Select from "vue3-select-component"
import "vue3-select-component/styles"

const value = ref<string | null>(null)

const options = [
  { label: "Option #1", value: "option_1" },
  { label: "Option #2", value: "option_2" },
]
</script>

<template>
  <Select v-model="value" :options="options" class="brand-select" />
</template>

<style scoped>
.brand-select {
  --vs-border-radius: 12px;
  --vs-outline-color: #0ea5e9;
}
</style>
```

Because the popover teleports to `document.body`, set popover-specific variables on `:root` or `[data-select-popover]` when needed:

```css
:root {
  --vs-menu-box-shadow: 0 8px 24px rgb(15 23 42 / 0.12);
}
```

### Variable reference

```css
:root {
  --vs-width: 100%;
  --vs-min-height: 38px;
  --vs-padding-y: 4px;
  --vs-padding-x: 8px;
  --vs-padding: var(--vs-padding-y) var(--vs-padding-x);
  --vs-border: 1px solid #e4e4e7;
  --vs-border-radius: 4px;
  --vs-font-size: 16px;
  --vs-font-weight: 400;
  --vs-font-family: inherit;
  --vs-text-color: #18181b;
  --vs-line-height: 1.5;
  --vs-placeholder-color: #52525b;
  --vs-background-color: #fff;
  --vs-disabled-background-color: #f4f4f5;
  --vs-outline-width: 1px;
  --vs-outline-color: #3b82f6;

  --vs-menu-offset-top: 8px;
  --vs-menu-height: 200px;
  --vs-menu-border: var(--vs-border);
  --vs-menu-background-color: var(--vs-background-color);
  --vs-menu-box-shadow: 0 1px 2px 0 rgb(0 0 0 / 0.05);
  --vs-menu-z-index: 50;

  --vs-option-padding: 8px 12px;
  --vs-option-hover-background-color: #f0f0f0;
  --vs-option-focused-background-color: #dbeafe;
  --vs-option-selected-background-color: #93c5fd;

  --vs-multi-value-background-color: #f4f4f5;
  --vs-multi-value-label-font-size: 12px;
  --vs-multi-value-delete-hover-background-color: #ff6467;

  --vs-icon-size: 20px;
  --vs-trailing-icon-size: 20px;
  --vs-spinner-size: 16px;
}
```

See [`src/styles.css`](https://github.com/TotomInc/vue3-select-component/blob/v1-dev/src/styles.css){rel="&#x22;nofollow&#x22;"} for the full list.

## Tailwind CSS

v1 does not include the v0 `classes` prop. For small changes to the assembled
`Select`, add a class to the component and use Tailwind's arbitrary variants to
target its stable data attributes:

```vue [App.vue]
<script setup lang="ts">
import { ref } from "vue"
import Select from "vue3-select-component"

const value = ref<string | null>(null)
const options = [
  { label: "Option #1", value: "option_1" },
  { label: "Option #2", value: "option_2" },
]
</script>

<template>
  <Select
    v-model="value"
    :options="options"
    class="[&_[data-select-trigger]]:rounded-xl [&_[data-select-trigger]]:border-sky-500"
  />
</template>
```

The popover is teleported to `document.body` by default, so descendant variants
on the assembled root cannot reach it. Target the global data hook from your CSS
instead:

```css [app.css]
@layer components {
  [data-select-popover] {
    @apply rounded-xl border-sky-500 shadow-lg;
  }

  [data-select-option][data-active="true"] {
    @apply bg-sky-100;
  }
}
```

When every element needs utility classes, compose the unstyled primitives and
put classes directly on them:

```vue [App.vue]
<script setup lang="ts">
import { ref } from "vue"
import {
  SelectInput,
  SelectListbox,
  SelectOption,
  SelectPopover,
  SelectRoot,
  SelectTrigger,
  SelectValue,
} from "vue3-select-component/primitives"

const value = ref<string | null>(null)
const options = [
  { label: "Option #1", value: "option_1" },
  { label: "Option #2", value: "option_2" },
]
</script>

<template>
  <SelectRoot v-model="value" :options="options">
    <SelectTrigger class="flex w-full rounded-xl border border-sky-500 px-3 py-2">
      <SelectValue />
      <SelectInput />
    </SelectTrigger>

    <SelectPopover class="mt-2 rounded-xl border bg-white shadow-lg">
      <SelectListbox>
        <SelectOption
          v-for="option in options"
          :key="option.value"
          :value="option.value"
          :label="option.label"
          class="cursor-pointer px-3 py-2 data-[active=true]:bg-sky-100"
        />
      </SelectListbox>
    </SelectPopover>
  </SelectRoot>
</template>
```

Skip the default stylesheet when you want a fully Tailwind-owned design.

## Headless styling with data attributes

Every primitive exposes stable `data-*` hooks for custom CSS:

| Attribute                   | Element                | State                       |
| --------------------------- | ---------------------- | --------------------------- |
| `data-select-root`          | Root wrapper           |                             |
| `data-assembled-select`     | Assembled root         |                             |
| `data-select-trigger`       | Trigger button         | `aria-expanded`             |
| `data-select-value`         | Value display          | `data-empty`                |
| `data-select-input`         | Search input           |                             |
| `data-select-popover`       | Dropdown panel         | `aria-hidden`               |
| `data-select-listbox`       | Listbox container      |                             |
| `data-select-option`        | Option row             | `data-value`, `data-active` |
| `data-select-tag`           | Multi-value tag        |                             |
| `data-select-tag-remove`    | Tag remove button      |                             |
| `data-select-clear`         | Clear button           |                             |
| `data-select-icon`          | Leading icon           |                             |
| `data-select-trailing-icon` | Trailing icon / loader | `data-open`, `data-loading` |
| `data-select-no-options`    | Empty state            |                             |
| `data-select-create-item`   | Create action          | `data-active`               |

### Style the trigger

```css
[data-select-trigger] {
  display: flex;
  align-items: center;
  gap: 0.5rem;
  width: 100%;
  min-height: 2.375rem;
  padding: 0.25rem 0.5rem;
  border: 1px solid #e4e4e7;
  border-radius: 0.375rem;
  background: #fff;
  cursor: pointer;
}

[data-select-trigger]:disabled {
  opacity: 0.5;
  cursor: not-allowed;
}
```

### Style options

Use `data-active` for keyboard-highlighted options and `aria-selected` for selected state:

```css
[data-select-option] {
  padding: 0.5rem 0.75rem;
  cursor: pointer;
}

[data-select-option][data-active="true"] {
  background: #dbeafe;
}

[data-select-option][aria-selected="true"] {
  background: #93c5fd;
}

[data-select-option][aria-disabled="true"] {
  opacity: 0.5;
  cursor: not-allowed;
}
```

### Style the popover

`SelectPopover` teleports to `document.body` by default. Use global CSS or unscoped styles with `[data-select-*]` hooks. Vue preserves scoped attribute selectors on teleported slot content, but parent `overflow` / `z-index` no longer constrain the panel.

```css
[data-select-popover] {
  margin-top: 0.5rem;
  border: 1px solid #e4e4e7;
  border-radius: 0.375rem;
  background: #fff;
  box-shadow: 0 1px 2px rgb(0 0 0 / 0.05);
  z-index: 50;
}
```

### Style multi-value tags

```css
[data-select-tag] {
  display: inline-flex;
  align-items: center;
  gap: 0.25rem;
  padding: 0.125rem 0.5rem;
  border-radius: 0.25rem;
  background: #f4f4f5;
  font-size: 0.75rem;
}

[data-select-tag-remove] {
  border: none;
  background: transparent;
  cursor: pointer;
  line-height: 1;
}
```

### Style the trailing icon

```css
[data-select-trailing-icon][data-open="true"] {
  transform: rotate(180deg);
}

[data-select-trailing-icon][data-loading="true"]::after {
  content: "";
  display: inline-block;
  width: 1rem;
  height: 1rem;
  border: 2px solid currentColor;
  border-top-color: transparent;
  border-radius: 50%;
  animation: spin 0.6s linear infinite;
}
```

## Scope styles to a wrapper

Wrap your select in a container class to scope overrides:

```vue [App.vue]
<script setup lang="ts">
import { ref } from "vue"
import Select from "vue3-select-component"
import "vue3-select-component/styles"

const value = ref<string | null>(null)

const options = [
  { label: "Option #1", value: "option_1" },
  { label: "Option #2", value: "option_2" },
]
</script>

<template>
  <div class="my-select">
    <Select v-model="value" :options="options" />
  </div>
</template>

<style scoped>
.my-select {
  --vs-border-radius: 12px;
}
</style>
```

For primitives, scope via a parent class or use `:deep()` as needed.


# TypeScript

Vue 3 Select Component is built with TypeScript. Types flow from your option data through `v-model`, props, events, and slots so you get autocompletion and compile-time checks in both the assembled `Select` and primitive APIs.

## Generic components

`Select` and `SelectRoot` use [Vue 3.3 generic components](https://vuejs.org/api/sfc-script-setup.html#generics){rel="&#x22;nofollow&#x22;"}. Two type parameters drive inference:

| Parameter       | Default                         | Role                                               |
| --------------- | ------------------------------- | -------------------------------------------------- |
| `OptionValue`   | `string`                        | The type bound to `v-model` (`string` or `number`) |
| `GenericOption` | `SelectOptionData<OptionValue>` | Your source option objects                         |

```ts
// Assembled Select: OptionValue first, then GenericOption
Select<OptionValue, GenericOption>

// Primitives: OptionValue only
SelectRoot<OptionValue>
```

TypeScript usually infers both parameters from `:options` and `v-model`. Pass them explicitly when wrapping the component or when inference is ambiguous.

## Use the SelectOptionData type

The canonical option shape is exported as `SelectOptionData` (alias of internal `SelectOption`):

```ts
import type { SelectOptionData } from "vue3-select-component"

type SelectOptionData<Value extends string | number = string> = {
  label: string
  value: Value
  disabled?: boolean
}
```

::note
v0 exported this type as 

`Option<T>`

. In v1, import 

`SelectOptionData`

 instead. See the 

[migration guide](https://vue3-select-component.vercel.app/guide/migration#update-typescript-imports)

.
::

## Configure value types

`option.value` and `v-model` share the same type. Use `string` or `number`:

```vue [App.vue]
<script setup lang="ts">
import type { SelectOptionData } from "vue3-select-component"
import { ref } from "vue"
import Select from "vue3-select-component"
import "vue3-select-component/styles"

type UserOption = SelectOptionData<number>

const selectedUser = ref<number | null>(null)

const userOptions: UserOption[] = [
  { label: "Alice", value: 1 },
  { label: "Bob", value: 2 },
  { label: "Charlie", value: 3 },
  // { label: "David", value: "invalid" } // Type error
]
</script>

<template>
  <Select
    v-model="selectedUser"
    :options="userOptions"
    placeholder="Pick a user"
  />
</template>
```

## Extend option properties

Add custom fields and keep them typed in mappers, filters, and events:

```vue [App.vue]
<script setup lang="ts">
import type { SelectOptionData } from "vue3-select-component"
import { ref } from "vue"
import Select from "vue3-select-component"
import "vue3-select-component/styles"

type UserOption = SelectOptionData<number> & { username: string }

const selectedUser = ref<number | null>(null)

const userOptions: UserOption[] = [
  { label: "Alice", value: 1, username: "alice15" },
  { label: "Bob", value: 2, username: "bob01" },
  { label: "Charlie", value: 3, username: "charlie20" },
]
</script>

<template>
  <Select
    v-model="selectedUser"
    :options="userOptions"
    :get-option-label="(option) => `${option.label} (${option.username})`"
    placeholder="Pick a user"
  />
</template>
```

With primitives, the same `UserOption` type flows into `SelectOption` slot props and `@option-selected` payloads.

## Validate v-model types

The component enforces consistency between `option.value` and `v-model`:

```vue
<script setup lang="ts">
import type { SelectOptionData } from "vue3-select-component"
import { ref } from "vue"
import Select from "vue3-select-component"
import "vue3-select-component/styles"

type UserOption = SelectOptionData<number>

// Incorrect: should be ref<number | null>(null)
const selectedUser = ref<string | null>(null)

const userOptions: UserOption[] = [
  { label: "Alice", value: 1 },
  { label: "Bob", value: 2 },
]
</script>

<template>
  <!-- Type error: string conflicts with number -->
  <Select
    v-model="selectedUser"
    :options="userOptions"
    placeholder="Pick a user"
  />
</template>
```

## Use SelectModelValue

The internal `v-model` type is `SelectModelValue<Value>`:

```ts
import type { SelectModelValue } from "vue3-select-component"

type SelectModelValue<Value> = Value | Value[] | null
```

In practice, bind a narrower type for each mode:

| Mode          | Bind as                   |
| ------------- | ------------------------- |
| Single select | `ref<Value | null>(null)` |
| Multi-select  | `ref<Value[]>([])`        |

```vue [App.vue]
<script setup lang="ts">
import type { SelectOptionData } from "vue3-select-component"
import { ref } from "vue"
import Select from "vue3-select-component"
import "vue3-select-component/styles"

type UserOption = SelectOptionData<number>

const single = ref<number | null>(null)
const multi = ref<number[]>([])

const userOptions: UserOption[] = [
  { label: "Alice", value: 1 },
  { label: "Bob", value: 2 },
]
</script>

<template>
  <Select v-model="single" :options="userOptions" />
  <Select v-model="multi" :options="userOptions" multiple />
</template>
```

## Type multi-select refs

When wrapping `Select`, pass both generics so events and options stay typed:

```vue [App.vue]
<script setup lang="ts">
import type { SelectOptionData } from "vue3-select-component"
import { ref } from "vue"
import Select from "vue3-select-component"
import "vue3-select-component/styles"

type UserOption = SelectOptionData<number>

const selectRef = ref<InstanceType<typeof Select<number, UserOption>>>()
const selectedUsers = ref<number[]>([])

const userOptions: UserOption[] = [
  { label: "Alice", value: 1 },
  { label: "Bob", value: 2 },
]
</script>

<template>
  <Select
    ref="selectRef"
    v-model="selectedUsers"
    :options="userOptions"
    multiple
  />
</template>
```

## Custom value mapping

When options do not follow `{ label, value }`, use `getOptionLabel` and `getOptionValue`. TypeScript infers `GenericOption` from your array:

```vue [App.vue]
<script setup lang="ts">
import { ref } from "vue"
import Select from "vue3-select-component"
import "vue3-select-component/styles"

type Role = { id: string; key: string }

const activeRole = ref<string | null>(null)

const roleOptions: Role[] = [
  { id: "Admin", key: "admin" },
  { id: "User", key: "user" },
  { id: "Guest", key: "guest" },
]
</script>

<template>
  <Select
    v-model="activeRole"
    :options="roleOptions"
    :get-option-label="(option) => option.id"
    :get-option-value="(option) => option.key"
    placeholder="Pick a role"
  />
</template>
```

::warning
Custom mappers weaken the link between your array type and 

`SelectOptionData`

. Prefer typed source objects and mappers over casting options to 

`SelectOptionData[]`

. See 

[Options](https://vue3-select-component.vercel.app/guide/options#use-custom-option-shapes)

 for runtime behavior.
::

If inference fails, set generics explicitly:

```vue
<Select<string, Role>
  v-model="activeRole"
  :options="roleOptions"
  :get-option-label="(option) => option.id"
  :get-option-value="(option) => option.key"
/>
```

## Typed events and filters

Assembled `Select` events receive your **source** option object, not the normalized `{ label, value }` shape:

```ts
import type { AssembledSelectEmits, SelectOptionData } from "vue3-select-component"

type UserOption = SelectOptionData<number> & { username: string }

// optionSelected: [option: UserOption]
// optionDeselected: [option: UserOption | null]
type SelectEvents = AssembledSelectEmits<UserOption>
```

`filterBy` on assembled `Select` also receives the source object:

```ts
type UserOption = SelectOptionData<number> & { username: string }

type FilterBy = (
  option: UserOption,
  label: string,
  search: string,
) => boolean

const filterBy: FilterBy = (option, label, search) =>
  label.toLowerCase().includes(search.toLowerCase())
  || option.username.toLowerCase().includes(search.toLowerCase())
```

On primitives, `SelectRoot` emits `OptionValue` (not the full option object). See [Events](https://vue3-select-component.vercel.app/api/events) for both APIs.

## Import component prop types

All public prop, emit, and slot types are exported for wrappers and design systems:

```ts
import type {
  AssembledSelectProps,
  AssembledSelectEmits,
  AssembledSelectSlots,
  SelectModelValue,
  SelectOptionData,
  SelectPopoverProps,
  SelectRootProps,
  SelectRootEmits,
  SelectTagRemoveSlotProps,
  SelectValueSlots,
} from "vue3-select-component"
```

See [Slots](https://vue3-select-component.vercel.app/api/slots#typescript) for the full list of slot and slot prop types.

Example wrapper:

```ts
import type { AssembledSelectProps, SelectOptionData } from "vue3-select-component"

type AppSelectProps<T extends string | number> =
  AssembledSelectProps<SelectOptionData<T>, T>
```

## Primitives typing

`SelectRoot` accepts normalized `SelectOptionData<Value>[]` and types `v-model` the same way as assembled `Select`:

```vue [App.vue]
<script setup lang="ts">
import type { SelectOptionData } from "vue3-select-component"
import { ref } from "vue"
import {
  SelectListbox,
  SelectNoOptions,
  SelectOption,
  SelectPopover,
  SelectRoot,
  SelectTrigger,
  SelectValue,
} from "vue3-select-component/primitives"
import "vue3-select-component/styles"

const selected = ref<string | null>(null)

const options: SelectOptionData<string>[] = [
  { label: "JavaScript", value: "js" },
  { label: "TypeScript", value: "ts" },
]
</script>

<template>
  <div data-assembled-select>
    <SelectRoot v-model="selected" :options="options">
      <SelectTrigger>
        <SelectValue placeholder="Pick a language" />
      </SelectTrigger>
      <SelectPopover>
        <SelectListbox>
          <SelectNoOptions />
          <SelectOption
            v-for="option in options"
            :key="option.value"
            :value="option.value"
            :label="option.label"
          />
        </SelectListbox>
      </SelectPopover>
    </SelectRoot>
  </div>
</template>
```

Popover-related prop types (`SelectPopoverProps`, `SelectPopoverContentProps`, and others) are exported from the package entry point for custom compositions.


# Accessibility

Vue 3 Select Component follows the [WAI-ARIA Combobox Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/){rel="&#x22;nofollow&#x22;"} for assistive technologies. The assembled `Select` and primitives share the same accessibility behavior.

## Overview

Built-in support includes:

- **ARIA attributes** for semantic markup (`combobox`, `listbox`, `option`)
- **Keyboard navigation** for full keyboard-only operation
- **Focus management** with `aria-activedescendant` on the searchable input
- **Screen reader support** with descriptive labels and state attributes

## Searchable vs non-searchable

The active control depends on `searchable`:

| Mode                             | Control element                   | ARIA owner                           |
| -------------------------------- | --------------------------------- | ------------------------------------ |
| `searchable` (assembled default) | `SelectInput` (`role="combobox"`) | Input owns the listbox relationship  |
| `searchable={false}`             | `SelectTrigger` (`<button>`)      | Button owns the listbox relationship |

In searchable mode, `SelectTrigger` is a layout wrapper (`<div>`). The input is the combobox. In non-searchable mode, the trigger button opens the menu and carries `aria-expanded`, `aria-haspopup`, and `aria-controls`.

Both APIs use the same primitives underneath. Pass label attributes to the control that is actually focusable.

## ARIA attributes

### Searchable combobox (`SelectInput`)

When `searchable` is enabled, the search input is the combobox control:

```html
<input
  role="combobox"
  aria-autocomplete="list"
  aria-haspopup="listbox"
  aria-expanded="true|false"
  aria-controls="v1-select-1-listbox"
  aria-activedescendant="select-option-3"
  autocomplete="off"
/>
```

| Attribute                  | Purpose                                                 |
| -------------------------- | ------------------------------------------------------- |
| `aria-expanded`            | Menu open (`true`) or closed (`false`)                  |
| `aria-haspopup="listbox"`  | Signals a listbox popup                                 |
| `aria-controls`            | References the listbox element ID                       |
| `aria-activedescendant`    | Points to the keyboard-focused option (only while open) |
| `aria-autocomplete="list"` | Suggestions appear in the listbox                       |

### Non-searchable trigger (`SelectTrigger`)

When search is disabled, the trigger renders as a `<button>`:

```html
<button
  type="button"
  aria-expanded="true|false"
  aria-haspopup="listbox"
  aria-controls="v1-select-1-listbox"
>
```

The button is disabled with the native `disabled` attribute. `SelectInput` is not rendered in this mode.

### Listbox (`SelectListbox`)

```html
<div
  role="listbox"
  aria-labelledby="v1-select-1-input"
  aria-multiselectable="true|false"
  tabindex="-1"
>
```

| Attribute              | Purpose                                                                 |
| ---------------------- | ----------------------------------------------------------------------- |
| `aria-labelledby`      | References the input ID in searchable mode, or the trigger ID otherwise |
| `aria-multiselectable` | `true` when `multiple` is enabled                                       |

### Options (`SelectOption`)

Each option renders as:

```html
<div
  role="option"
  aria-selected="true|false"
  aria-disabled="true|false"
  data-active="true|false"
>
```

| Attribute       | Purpose                                                      |
| --------------- | ------------------------------------------------------------ |
| `aria-selected` | Whether the option is in the current selection               |
| `aria-disabled` | Whether the option cannot be selected                        |
| `data-active`   | Keyboard highlight state (style with `[data-active="true"]`) |

Disabled options are skipped during keyboard navigation.

### Popover panel (`SelectPopover`)

The dropdown panel exposes visibility to assistive technologies:

```html
<div data-select-popover aria-hidden="true|false" hidden>
```

When the menu is closed, the panel is hidden and marked `aria-hidden="true"`. Auto-focus on open is prevented so focus stays on the input or trigger.

### Interactive controls

| Element                         | Accessible name                   |
| ------------------------------- | --------------------------------- |
| Clear button (`SelectClear`)    | `aria-label="Clear selection"`    |
| Tag remove button (`SelectTag`) | `aria-label="Remove"`             |
| Leading / trailing icons        | `aria-hidden="true"` (decorative) |
| Empty state (`SelectNoOptions`) | `role="status"`                   |

Customize tag remove labels in the `tag-remove` slot if you need option-specific text. See [Slots](https://vue3-select-component.vercel.app/api/slots).

## Label your select

Associate the select with a visible label using standard HTML attributes. On the assembled `Select`, `id`, `aria-label`, `aria-labelledby`, `aria-describedby`, `aria-invalid`, and `aria-required` are forwarded to the active control (`SelectInput` or `SelectTrigger`).

### Assembled Select

```vue [App.vue]
<script setup lang="ts">
import { ref } from "vue"
import Select from "vue3-select-component"
import "vue3-select-component/styles"

const country = ref<string | null>(null)

const countries = [
  { label: "France", value: "FR" },
  { label: "Germany", value: "DE" },
]
</script>

<template>
  <label id="country-label" for="country-select">Country</label>
  <Select
    id="country-select"
    v-model="country"
    :options="countries"
    aria-labelledby="country-label"
    aria-required="true"
    placeholder="Select a country"
  />
</template>
```

Add helper or error text with `aria-describedby`:

```vue [App.vue]
<script setup lang="ts">
import { ref } from "vue"
import Select from "vue3-select-component"
import "vue3-select-component/styles"

const country = ref<string | null>(null)
const hasError = ref(false)

const countries = [
  { label: "France", value: "FR" },
  { label: "Germany", value: "DE" },
]
</script>

<template>
  <label id="country-label" for="country-select">Country</label>
  <p id="country-helper">Pick the country where you live.</p>
  <Select
    id="country-select"
    v-model="country"
    :options="countries"
    aria-labelledby="country-label"
    aria-describedby="country-helper"
    :aria-invalid="hasError"
    placeholder="Select a country"
  />
</template>
```

### Primitives

Pass the same attributes to the focusable primitive:

```vue [CustomSelect.vue]
<script setup lang="ts">
import { ref } from "vue"
import {
  SelectInput,
  SelectListbox,
  SelectNoOptions,
  SelectOption,
  SelectPopover,
  SelectRoot,
  SelectTrigger,
  SelectValue,
} from "vue3-select-component/primitives"
import "vue3-select-component/styles"

const model = ref<string | null>(null)

const options = [
  { label: "JavaScript", value: "js" },
  { label: "TypeScript", value: "ts" },
]
</script>

<template>
  <label id="language-label" for="language-select">Language</label>

  <div data-assembled-select>
    <SelectRoot v-model="model" :options="options" searchable>
      <SelectTrigger>
        <SelectValue placeholder="Pick a language" />
        <SelectInput
          id="language-select"
          aria-labelledby="language-label"
        />
      </SelectTrigger>

      <SelectPopover>
        <SelectListbox>
          <SelectNoOptions />
          <SelectOption
            v-for="opt in options"
            :key="opt.value"
            :value="opt.value"
            :label="opt.label"
          />
        </SelectListbox>
      </SelectPopover>
    </SelectRoot>
  </div>
</template>
```

When `searchable` is disabled, pass label attributes to `SelectTrigger` instead of `SelectInput`.

## Keyboard navigation

Keyboard handling is shared between assembled `Select` and primitives.

### When the menu is closed

| Key                     | Action                                                                            |
| ----------------------- | --------------------------------------------------------------------------------- |
| `ArrowDown` / `ArrowUp` | Open the menu and highlight the first enabled option                              |
| `Space`                 | Open the menu (trigger only, when search text is empty)                           |
| `Enter`                 | Open the menu on a focused non-searchable trigger button (native button behavior) |
| `Tab`                   | Move focus to the next focusable element                                          |

In searchable mode, focusing or clicking the input also opens the menu.

### When the menu is open

| Key         | Action                                                                                  |
| ----------- | --------------------------------------------------------------------------------------- |
| `ArrowDown` | Move to the next enabled option (wraps to the first)                                    |
| `ArrowUp`   | Move to the previous enabled option (wraps to the last)                                 |
| `Enter`     | Select the active option                                                                |
| `Space`     | Select the active option when search text is empty and focus is not in the search input |
| `Escape`    | Close the menu without selecting                                                        |
| `Tab`       | Close the menu and move focus                                                           |
| `Backspace` | Remove the last selected tag when search is empty (multi-select only)                   |

Single-select closes the menu after selection by default. Multi-select keeps it open so users can pick multiple values. Override with `closeOnSelect`.

### Search behavior

When `searchable` is enabled:

- Typing filters options in real time
- The active option syncs to the first matching result
- Arrow keys move within the filtered list
- The `@search` event fires as the query changes

## Focus management

When the menu opens, the first enabled option becomes active. In searchable mode, focus stays on the input while `aria-activedescendant` points at the highlighted option.

Disabled options are skipped:

```vue [App.vue]
<script setup lang="ts">
import { ref } from "vue"
import Select from "vue3-select-component"
import "vue3-select-component/styles"

const selected = ref<string | null>(null)
</script>

<template>
  <Select
    v-model="selected"
    :options="[
      { label: 'Available', value: '1' },
      { label: 'Unavailable', value: '2', disabled: true },
    ]"
    placeholder="Pick an option"
  />
</template>
```

### Visual focus indicator

Keyboard-highlighted options use `data-active="true"`. Default assembled styles map this to a focus background. Customize with CSS variables:

```css
:root {
  --vs-option-focused-background-color: #dbeafe;
  --vs-option-focused-text-color: #18181b;
}
```

See [Styling](https://vue3-select-component.vercel.app/guide/styling) for the full variable list and headless `data-*` hooks.

## Dismiss behavior

- Click outside the select closes the menu
- `Tab` away closes an open menu
- `Escape` closes without selecting

## Screen reader support

Assistive technologies can observe:

- Menu open/close via `aria-expanded` on the control and `aria-hidden` on the popover
- The listbox name via `aria-labelledby`
- The active option via `aria-activedescendant` while navigating
- Selection state via `aria-selected` on each option
- Disabled state via `aria-disabled`
- Empty results via `role="status"` on `SelectNoOptions`

Selected values render as visible text in `SelectValue` (single label or multi-select tags). Add `aria-label` or `aria-labelledby` on the control when the visible label alone is not enough.

## Unique IDs

Each select instance generates stable IDs for ARIA wiring:

```html
<!-- Searchable -->
<input id="v1-select-1-input" role="combobox" aria-controls="v1-select-1-listbox">
<div id="v1-select-1-listbox" role="listbox" aria-labelledby="v1-select-1-input">

<!-- Non-searchable -->
<button id="v1-select-1-trigger" aria-controls="v1-select-1-listbox">
<div id="v1-select-1-listbox" role="listbox" aria-labelledby="v1-select-1-trigger">
```

Option elements receive unique IDs for `aria-activedescendant`. Pass a custom `id` to `SelectInput` when you need a predictable input ID for `for`/`aria-labelledby` wiring.

## Test with assistive technology

Verify these scenarios during development:

1. Open and close the menu with keyboard only
2. Navigate options with arrow keys and select with Enter
3. Confirm screen readers announce expanded/collapsed state
4. Verify disabled options are skipped
5. In multi-select, confirm tags are visible and removable
6. Repeat in both searchable and non-searchable modes
7. Repeat with assembled `Select` and a custom primitives layout

## Resources

- [WAI-ARIA Combobox Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/){rel="&#x22;nofollow&#x22;"}
- [WAI-ARIA Listbox Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/listbox/){rel="&#x22;nofollow&#x22;"}
- [ARIA Authoring Practices Guide](https://www.w3.org/WAI/ARIA/apg/){rel="&#x22;nofollow&#x22;"}


# Migration

Still on v0? Read the [v0 documentation](https://v0-vue3-select-component.vercel.app/){rel="&#x22;nofollow&#x22;"} for the previous API.

v1 is a breaking release. It adds primitives alongside the assembled `Select`. This guide covers the main changes from v0.

## Understand the new architecture

| v0                               | v1                                            |
| -------------------------------- | --------------------------------------------- |
| Single monolithic component      | Assembled `Select` + primitives               |
| Bundled CSS (`--vs-*` variables) | Optional default styles + headless primitives |
| Slots on `VueSelect`             | Slots on individual primitives                |
| `Option<T>` type                 | `SelectOptionData<T>` type                    |

The assembled `Select` covers common use cases with v1 prop names only. v0 prop aliases are **not** supported, rename them during migration.

## Rename boolean props

v1 uses clearer boolean prop names. Update every usage in your templates and script setup:

| v0 prop        | v1 prop      |
| -------------- | ------------ |
| `isMulti`      | `multiple`   |
| `isSearchable` | `searchable` |
| `isClearable`  | `clearable`  |
| `isDisabled`   | `disabled`   |
| `isLoading`    | `loading`    |

```vue
<!-- v0 -->
<Select :is-multi="true" :is-searchable="true" />

<!-- v1 -->
<Select multiple />
```

Primitives accept v1 names only. Assembled `Select` is searchable by default, so keep `searchable` only when you need to pass a dynamic value.

## Update imports

```ts
// v0
import VueSelect from "vue3-select-component"
import "vue3-select-component/styles"

// v1
import Select from "vue3-select-component"
import "vue3-select-component/styles"

// Primitives (new)
import { SelectRoot, SelectTrigger } from "vue3-select-component/primitives"
```

## Update bundled CSS

Keep `import "vue3-select-component/styles"` for the assembled `Select`. Default styles still expose `--vs-*` variables and target `data-*` hooks instead of v0 class names.

For custom primitive compositions, skip the stylesheet and style via `data-*` selectors. See [Styling](https://vue3-select-component.vercel.app/guide/styling).

### Replace the `classes` prop

The v0 `classes` prop was removed in v1. For Tailwind or another utility CSS
framework, use arbitrary variants with the assembled `Select`'s stable `data-*`
hooks, or compose the unstyled primitives and apply classes directly to each
element. The [Tailwind CSS guide](https://vue3-select-component.vercel.app/guide/styling#tailwind-css) shows both
approaches and explains how to style the teleported popover.

## Map slots to primitives

v0 slots on the monolithic component map to primitive slots:

| v0 slot        | v1 equivalent                                      |
| -------------- | -------------------------------------------------- |
| `#option`      | `SelectOption` default slot                        |
| `#value`       | `SelectValue` default slot                         |
| `#tag`         | `SelectTag` default + `remove` slots               |
| `#tag-content` | `SelectTag` default slot                           |
| `#loading`     | `SelectTrailingIcon` default slot (`loading` prop) |

The assembled `Select` exposes `icon`, `trailing-icon`, `tag-remove`, `no-options`, `create-item`, and `clear` slots. Enable the clear button with `clearable`. Use primitives for broader customization.

## Event payload differences

On &#x2A;*assembled `Select`**, events still emit source option objects (v0 behavior):

```vue
<Select @option-selected="(option) => console.log(option)" />
```

On **`SelectRoot` primitives**, events emit raw values:

```vue
<SelectRoot @option-selected="(value) => console.log(value)" />
```

Event names use camelCase in script (`@optionSelected`) and kebab-case in templates (`@option-selected`).

## Removed v0 features

These v0 props are not part of v1 yet. Use primitives to implement equivalent behavior:

| v0 prop               | v1 approach                                              |
| --------------------- | -------------------------------------------------------- |
| `displayedOptions`    | Filter `options` yourself or use custom `filterBy`       |
| `isTaggable`          | Handle creation in your app and add options dynamically  |
| `isMenuOpen`          | Control open state via primitives or custom composition  |
| `hideSelectedOptions` | Use `hideSelected` on assembled `Select` or `SelectRoot` |
| `aria` prop           | Apply ARIA attributes on primitive elements directly     |

## Update TypeScript imports

```ts
// v0
import type { Option } from "vue3-select-component"

// v1
import type { SelectOptionData, SelectModelValue } from "vue3-select-component"
```


# Examples

Live examples for common setups. Each demo prints the current `v-model` value below the control.

## Assembled select

The default export wires up primitives with sensible defaults. Use these patterns when the built-in UX is enough.

### Clearable

Show a clear button when a value is selected.

::client-only
:example-clearable-demo

#fallback
:select-demo-fallback
::

```vue [App.vue]
<script setup lang="ts">
import { ref } from "vue"
import Select from "vue3-select-component"
import "vue3-select-component/styles"

const selected = ref<string | null>("FR")

const options = [
  { label: "France", value: "FR" },
  { label: "Spain", value: "ES" },
  { label: "United Kingdom", value: "GB" },
  { label: "Germany", value: "DE" },
  { label: "Italy", value: "IT" },
]
</script>

<template>
  <Select
    v-model="selected"
    clearable
    :options="options"
    placeholder="Select a country"
  />
</template>
```

### Non-searchable

Turn off the search input for a button-only select.

::client-only
:example-non-searchable-demo

#fallback
:select-demo-fallback
::

```vue [App.vue]
<script setup lang="ts">
import { ref } from "vue"
import Select from "vue3-select-component"
import "vue3-select-component/styles"

const selected = ref<string | null>(null)

const options = [
  { label: "Option #1", value: "option_1" },
  { label: "Option #2", value: "option_2" },
  { label: "Option #3", value: "option_3" },
]
</script>

<template>
  <Select
    v-model="selected"
    :searchable="false"
    :options="options"
    placeholder="Select an option"
  />
</template>
```

### Disabled

Disable the entire control when the field should not be editable.

::client-only
:example-disabled-demo

#fallback
:select-demo-fallback
::

```vue [App.vue]
<script setup lang="ts">
import { ref } from "vue"
import Select from "vue3-select-component"
import "vue3-select-component/styles"

const selected = ref<string | null>("FR")

const options = [
  { label: "France", value: "FR" },
  { label: "Spain", value: "ES" },
  { label: "Germany", value: "DE" },
]
</script>

<template>
  <Select
    v-model="selected"
    disabled
    :options="options"
  />
</template>
```

### Loading

Expose a loading state on the trigger while options are fetched.

::client-only
:example-loading-demo

#fallback
:select-demo-fallback
::

```vue [App.vue]
<script setup lang="ts">
import { ref } from "vue"
import Select from "vue3-select-component"
import "vue3-select-component/styles"

const selected = ref<string | null>(null)
const isLoading = ref(true)

const options = [
  { label: "France", value: "FR" },
  { label: "Spain", value: "ES" },
  { label: "Germany", value: "DE" },
]
</script>

<template>
  <Select
    v-model="selected"
    :loading="isLoading"
    :options="options"
    placeholder="Select a country"
  />
</template>
```

### Hide selected options

In multi-select mode, remove picked options from the dropdown while keeping them as tags in the trigger.

::client-only
:example-hide-selected-demo

#fallback
:select-demo-fallback
::

```vue [App.vue]
<script setup lang="ts">
import { ref } from "vue"
import Select from "vue3-select-component"
import "vue3-select-component/styles"

const selected = ref<string[]>(["js"])

const options = [
  { label: "JavaScript", value: "js" },
  { label: "TypeScript", value: "ts" },
  { label: "Python", value: "py" },
  { label: "Rust", value: "rs" },
]
</script>

<template>
  <Select
    v-model="selected"
    multiple
    hide-selected
    :options="options"
    placeholder="Select languages"
  />
</template>
```

### Disabled options

Mark individual options as disabled so they cannot be selected.

::client-only
:example-disabled-options-demo

#fallback
:select-demo-fallback
::

```vue [App.vue]
<script setup lang="ts">
import { ref } from "vue"
import Select from "vue3-select-component"
import "vue3-select-component/styles"

const selected = ref<string | null>(null)
</script>

<template>
  <Select
    v-model="selected"
    :options="[
      { label: 'France', value: 'FR' },
      { label: 'Spain', value: 'ES', disabled: true },
      { label: 'Germany', value: 'DE' },
    ]"
    placeholder="Select a country"
  />
</template>
```

### Close on select

By default, the menu stays open in multi-select mode. Set `close-on-select` to dismiss it after each pick.

::client-only
:example-close-on-select-demo

#fallback
:select-demo-fallback
::

```vue [App.vue]
<script setup lang="ts">
import { ref } from "vue"
import Select from "vue3-select-component"
import "vue3-select-component/styles"

const selected = ref<string[]>([])

const options = [
  { label: "JavaScript", value: "js" },
  { label: "TypeScript", value: "ts" },
  { label: "Python", value: "py" },
]
</script>

<template>
  <Select
    v-model="selected"
    multiple
    close-on-select
    :options="options"
    placeholder="Select languages"
  />
</template>
```

## Primitives

Compose `SelectRoot`, `SelectTrigger`, `SelectPopover`, and the rest when you need custom layout, slots, or popover behavior. Demos use `data-assembled-select` on a wrapper so default styles apply while you own the DOM tree.

### Full composition

Wire every trigger and listbox primitive yourself. Add a leading icon, search input, clear button, and a custom trailing icon.

::client-only
:example-primitive-composed-demo

#fallback
:select-demo-fallback
::

```vue [CustomSelect.vue]
<script setup lang="ts">
import { ref } from "vue"
import {
  SelectClear,
  SelectIcon,
  SelectInput,
  SelectListbox,
  SelectNoOptions,
  SelectOption,
  SelectPopover,
  SelectRoot,
  SelectTrailingIcon,
  SelectTrigger,
  SelectValue,
} from "vue3-select-component/primitives"
import "vue3-select-component/styles"

const selected = ref<string | null>(null)

const options = [
  { label: "France", value: "FR" },
  { label: "Spain", value: "ES" },
  { label: "Germany", value: "DE" },
]
</script>

<template>
  <div data-assembled-select>
    <SelectRoot
      v-model="selected"
      searchable
      clearable
    >
      <SelectTrigger>
        <SelectIcon aria-hidden="true">
          <!-- globe icon -->
        </SelectIcon>
        <SelectValue placeholder="Select a country" />
        <SelectInput />
        <SelectTrailingIcon>
          <template #default="{ open }">
            <span aria-hidden="true">{{ open ? "▲" : "▼" }}</span>
          </template>
        </SelectTrailingIcon>
        <SelectClear />
      </SelectTrigger>

      <SelectPopover>
        <SelectListbox>
          <SelectNoOptions />
          <SelectOption
            v-for="option in options"
            :key="option.value"
            :value="option.value"
            :label="option.label"
          />
        </SelectListbox>
      </SelectPopover>
    </SelectRoot>
  </div>
</template>
```

### Rich option rows

Render two-line options with declarative `SelectOption` children and a custom default slot.

::client-only
:example-primitive-rich-options-demo

#fallback
:select-demo-fallback
::

```vue [CustomSelect.vue]
<script setup lang="ts">
import { ref } from "vue"
import {
  SelectInput,
  SelectListbox,
  SelectNoOptions,
  SelectOption,
  SelectPopover,
  SelectRoot,
  SelectTrailingIcon,
  SelectTrigger,
  SelectValue,
} from "vue3-select-component/primitives"
import "vue3-select-component/styles"

type LanguageOption = {
  label: string
  value: string
  description: string
}

const selected = ref<string | null>(null)

const options: LanguageOption[] = [
  { label: "JavaScript", value: "js", description: "Runs in browsers and Node.js" },
  { label: "TypeScript", value: "ts", description: "Typed superset of JavaScript" },
  { label: "Python", value: "py", description: "General-purpose scripting" },
  { label: "Rust", value: "rs", description: "Systems programming with ownership" },
]
</script>

<template>
  <div data-assembled-select>
    <SelectRoot v-model="selected" searchable>
      <SelectTrigger>
        <SelectValue placeholder="Pick a language" />
        <SelectInput />
        <SelectTrailingIcon />
      </SelectTrigger>

      <SelectPopover>
        <SelectListbox>
          <SelectNoOptions />
          <SelectOption
            v-for="option in options"
            :key="option.value"
            :value="option.value"
            :label="option.label"
          >
            <span class="option">
              <strong>{{ option.label }}</strong>
              <span>{{ option.description }}</span>
            </span>
          </SelectOption>
        </SelectListbox>
      </SelectPopover>
    </SelectRoot>
  </div>
</template>
```

### Grouped options

::note
You do not need group primitives for a flat list. Render 

`SelectOption`

 children directly inside 

`SelectListbox`

.
::

::client-only
:example-primitive-groups-demo

#fallback
:select-demo-fallback
::

```vue [CustomSelect.vue]
<script setup lang="ts">
import { ref } from "vue"
import {
  SelectGroup,
  SelectGroupLabel,
  SelectInput,
  SelectListbox,
  SelectOption,
  SelectPopover,
  SelectRoot,
  SelectTrailingIcon,
  SelectTrigger,
  SelectValue,
} from "vue3-select-component/primitives"
import "vue3-select-component/styles"

const selected = ref<string | null>(null)

const frontendOptions = [
  { label: "Vue", value: "vue" },
  { label: "React", value: "react" },
  { label: "Svelte", value: "svelte" },
]

const backendOptions = [
  { label: "Node.js", value: "node" },
  { label: "Go", value: "go" },
  { label: "Rust", value: "rust" },
]
</script>

<template>
  <div data-assembled-select>
    <SelectRoot v-model="selected" searchable>
      <SelectTrigger>
        <SelectValue placeholder="Pick a technology" />
        <SelectInput />
        <SelectTrailingIcon />
      </SelectTrigger>

      <SelectPopover>
        <SelectListbox>
          <SelectGroup>
            <SelectGroupLabel>Frontend</SelectGroupLabel>
            <SelectOption
              v-for="option in frontendOptions"
              :key="option.value"
              v-bind="option"
            />
          </SelectGroup>

          <SelectGroup>
            <SelectGroupLabel>Backend</SelectGroupLabel>
            <SelectOption
              v-for="option in backendOptions"
              :key="option.value"
              v-bind="option"
            />
          </SelectGroup>
        </SelectListbox>
      </SelectPopover>
    </SelectRoot>
  </div>
</template>
```

### Group separators

::note
You do not need group primitives for a flat list. Render 

`SelectOption`

 children directly inside 

`SelectListbox`

.
::

Add `SelectSeparator` between sections when grouped options need a stronger visual break.

::client-only
:example-primitive-separator-demo

#fallback
:select-demo-fallback
::

```vue [CustomSelect.vue]
<script setup lang="ts">
import { ref } from "vue"
import {
  SelectGroup,
  SelectGroupLabel,
  SelectListbox,
  SelectOption,
  SelectPopover,
  SelectRoot,
  SelectSeparator,
  SelectTrailingIcon,
  SelectTrigger,
  SelectValue,
} from "vue3-select-component/primitives"
import "vue3-select-component/styles"

const selected = ref<string | null>(null)

const frequentOptions = [
  { label: "France", value: "FR" },
  { label: "Japan", value: "JP" },
]

const otherOptions = [
  { label: "Brazil", value: "BR" },
  { label: "Canada", value: "CA" },
]
</script>

<template>
  <div data-assembled-select>
    <SelectRoot v-model="selected" :searchable="false">
      <SelectTrigger>
        <SelectValue placeholder="Pick a country" />
        <SelectTrailingIcon />
      </SelectTrigger>

      <SelectPopover>
        <SelectListbox>
          <SelectGroup>
            <SelectGroupLabel>Frequent</SelectGroupLabel>
            <SelectOption
              v-for="option in frequentOptions"
              :key="option.value"
              v-bind="option"
            />
          </SelectGroup>

          <SelectSeparator />

          <SelectGroup>
            <SelectGroupLabel>Other countries</SelectGroupLabel>
            <SelectOption
              v-for="option in otherOptions"
              :key="option.value"
              v-bind="option"
            />
          </SelectGroup>
        </SelectListbox>
      </SelectPopover>
    </SelectRoot>
  </div>
</template>
```

### Custom value display

Override how the selected value appears in the trigger with the `SelectValue` default slot.

::client-only
:example-primitive-custom-value-demo

#fallback
:select-demo-fallback
::

```vue [CustomSelect.vue]
<script setup lang="ts">
import { ref } from "vue"
import {
  SelectInput,
  SelectListbox,
  SelectNoOptions,
  SelectOption,
  SelectPopover,
  SelectRoot,
  SelectTrailingIcon,
  SelectTrigger,
  SelectValue,
} from "vue3-select-component/primitives"
import "vue3-select-component/styles"

const selected = ref<string | null>("ts")

const options = [
  { label: "JavaScript", value: "js" },
  { label: "TypeScript", value: "ts" },
  { label: "Python", value: "py" },
]
</script>

<template>
  <div data-assembled-select>
    <SelectRoot v-model="selected" searchable>
      <SelectTrigger>
        <SelectValue placeholder="Pick a language">
          <template #default="{ selectedOptions }">
            <span v-if="selectedOptions[0]">
              Selected: {{ selectedOptions[0].label }}
            </span>
          </template>
        </SelectValue>
        <SelectInput />
        <SelectTrailingIcon />
      </SelectTrigger>

      <SelectPopover>
        <SelectListbox>
          <SelectNoOptions />
          <SelectOption
            v-for="option in options"
            :key="option.value"
            :value="option.value"
            :label="option.label"
          />
        </SelectListbox>
      </SelectPopover>
    </SelectRoot>
  </div>
</template>
```

### Multi-select tags

Customize tag remove buttons and option checkmarks in multi-select mode.

::client-only
:example-primitive-multi-tags-demo

#fallback
:select-demo-fallback
::

```vue [CustomSelect.vue]
<script setup lang="ts">
import { ref } from "vue"
import {
  SelectInput,
  SelectListbox,
  SelectNoOptions,
  SelectOption,
  SelectPopover,
  SelectRoot,
  SelectTrailingIcon,
  SelectTrigger,
  SelectValue,
} from "vue3-select-component/primitives"
import "vue3-select-component/styles"

const selected = ref<string[]>(["FR", "DE"])

const options = [
  { label: "France", value: "FR" },
  { label: "Spain", value: "ES" },
  { label: "Germany", value: "DE" },
]
</script>

<template>
  <div data-assembled-select>
    <SelectRoot v-model="selected" multiple searchable>
      <SelectTrigger>
        <SelectValue placeholder="Select countries">
          <template #tag-remove="{ label }">
            <span :aria-label="`Remove ${label}`">×</span>
          </template>
        </SelectValue>
        <SelectInput />
        <SelectTrailingIcon />
      </SelectTrigger>

      <SelectPopover>
        <SelectListbox>
          <SelectNoOptions />
          <SelectOption
            v-for="option in options"
            :key="option.value"
            :value="option.value"
            :label="option.label"
          >
            <template #checkmark>✓</template>
          </SelectOption>
        </SelectListbox>
      </SelectPopover>
    </SelectRoot>
  </div>
</template>
```

### Create item

Let users add a value from the search query. Handle `@create` to push into your options list and update `v-model`.

::client-only
:example-primitive-create-item-demo

#fallback
:select-demo-fallback
::

```vue [CustomSelect.vue]
<script setup lang="ts">
import { ref } from "vue"
import {
  SelectCreateItem,
  SelectInput,
  SelectListbox,
  SelectNoOptions,
  SelectOption,
  SelectPopover,
  SelectRoot,
  SelectTrailingIcon,
  SelectTrigger,
  SelectValue,
} from "vue3-select-component/primitives"
import "vue3-select-component/styles"

const statuses = ref(["Backlog", "Todo", "In Progress", "Done"])
const selected = ref("Backlog")

function onCreate(item: string) {
  statuses.value.push(item)
  selected.value = item
}
</script>

<template>
  <div data-assembled-select>
    <SelectRoot
      v-model="selected"
      searchable
      create-item
      @create="onCreate"
    >
      <SelectTrigger>
        <SelectValue placeholder="Pick or create a status" />
        <SelectInput />
        <SelectTrailingIcon />
      </SelectTrigger>

      <SelectPopover>
        <SelectListbox>
          <SelectNoOptions />
          <SelectOption
            v-for="status in statuses"
            :key="status"
            :value="status"
            :label="status"
          />
          <SelectCreateItem>
            <template #default="{ searchValue }">
              Add "{{ searchValue }}"
            </template>
          </SelectCreateItem>
        </SelectListbox>
      </SelectPopover>
    </SelectRoot>
  </div>
</template>
```

### Custom empty state

Replace the default "No options" message when filtering returns no matches.

::client-only
:example-primitive-no-options-demo

#fallback
:select-demo-fallback
::

```vue [CustomSelect.vue]
<script setup lang="ts">
import { ref } from "vue"
import {
  SelectInput,
  SelectListbox,
  SelectNoOptions,
  SelectOption,
  SelectPopover,
  SelectRoot,
  SelectTrailingIcon,
  SelectTrigger,
  SelectValue,
} from "vue3-select-component/primitives"
import "vue3-select-component/styles"

const selected = ref<string | null>(null)

const options = [
  { label: "France", value: "FR" },
  { label: "Spain", value: "ES" },
  { label: "Germany", value: "DE" },
]
</script>

<template>
  <div data-assembled-select>
    <SelectRoot v-model="selected" searchable>
      <SelectTrigger>
        <SelectValue placeholder="Search countries" />
        <SelectInput />
        <SelectTrailingIcon />
      </SelectTrigger>

      <SelectPopover>
        <SelectListbox>
          <SelectNoOptions>
            <template #default="{ searchValue }">
              No country matches "{{ searchValue }}"
            </template>
          </SelectNoOptions>
          <SelectOption
            v-for="option in options"
            :key="option.value"
            :value="option.value"
            :label="option.label"
          />
        </SelectListbox>
      </SelectPopover>
    </SelectRoot>
  </div>
</template>
```

### Filter by extra fields

Pass a custom `filterBy` to `SelectRoot` and render extra metadata in each `SelectOption` slot.

::client-only
:example-primitive-region-filter-demo

#fallback
:select-demo-fallback
::

```vue [CustomSelect.vue]
<script setup lang="ts">
import { ref } from "vue"
import {
  SelectInput,
  SelectListbox,
  SelectNoOptions,
  SelectOption,
  SelectPopover,
  SelectRoot,
  SelectTrailingIcon,
  SelectTrigger,
  SelectValue,
} from "vue3-select-component/primitives"
import "vue3-select-component/styles"

type CountryRecord = {
  name: string
  code: string
  region: string
}

const selected = ref<string | null>(null)

const countries: CountryRecord[] = [
  { name: "France", code: "FR", region: "Europe" },
  { name: "Japan", code: "JP", region: "Asia" },
  { name: "Brazil", code: "BR", region: "South America" },
  { name: "Canada", code: "CA", region: "North America" },
]

function filterByRegion(
  option: { label: string; value: string },
  search: string,
) {
  const query = search.trim().toLowerCase()

  if (!query) {
    return true
  }

  const record = countries.find((entry) => entry.code === option.value)

  return option.label.toLowerCase().includes(query)
    || record?.region.toLowerCase().includes(query) === true
}
</script>

<template>
  <div data-assembled-select>
    <SelectRoot
      v-model="selected"
      searchable
      :filter-by="filterByRegion"
    >
      <SelectTrigger>
        <SelectValue placeholder="Search by country or region" />
        <SelectInput />
        <SelectTrailingIcon />
      </SelectTrigger>

      <SelectPopover>
        <SelectListbox>
          <SelectNoOptions />
          <SelectOption
            v-for="country in countries"
            :key="country.code"
            :value="country.code"
            :label="country.name"
          >
            <span>{{ country.name }}</span>
            <span>{{ country.region }}</span>
          </SelectOption>
        </SelectListbox>
      </SelectPopover>
    </SelectRoot>
  </div>
</template>
```

### Popover placement

Control dropdown position with reka-ui popover props on `SelectPopover`.

::client-only
:example-primitive-popover-placement-demo

#fallback
:select-demo-fallback
::

```vue [CustomSelect.vue]
<script setup lang="ts">
import { ref } from "vue"
import {
  SelectListbox,
  SelectNoOptions,
  SelectOption,
  SelectPopover,
  SelectRoot,
  SelectTrailingIcon,
  SelectTrigger,
  SelectValue,
} from "vue3-select-component/primitives"
import "vue3-select-component/styles"

const selected = ref<string | null>(null)

const options = [
  { label: "Option #1", value: "option_1" },
  { label: "Option #2", value: "option_2" },
  { label: "Option #3", value: "option_3" },
]
</script>

<template>
  <div data-assembled-select>
    <SelectRoot v-model="selected" :searchable="false">
      <SelectTrigger>
        <SelectValue placeholder="Open to inspect placement" />
        <SelectTrailingIcon />
      </SelectTrigger>

      <SelectPopover side="top" align="end" :side-offset="8">
        <SelectListbox>
          <SelectNoOptions />
          <SelectOption
            v-for="option in options"
            :key="option.value"
            :value="option.value"
            :label="option.label"
          />
        </SelectListbox>
      </SelectPopover>
    </SelectRoot>
  </div>
</template>
```

## Next steps

- [Complex use cases](https://vue3-select-component.vercel.app/guide/complex-use-cases) for advanced patterns like virtualized lists
- [Primitives guide](https://vue3-select-component.vercel.app/guide/primitives) for architecture and option registration
- [Slots reference](https://vue3-select-component.vercel.app/api/slots) for every customization point
- [Browse all props](https://vue3-select-component.vercel.app/api/props) for flags, popover options, and mappers


# Deep Dive

The assembled `Select` is not a separate implementation. It is a fixed composition of primitives with extra glue for common app data shapes, events, and form attributes.

If you already use `Select` in your app, this page shows what happens under the hood and where to customize when defaults are not enough.

## Same tree as primitives

Assembled `Select` renders the same primitive tree described in [Primitives](https://vue3-select-component.vercel.app/guide/primitives). `SelectRoot` owns state. Child primitives read it through context.

```text
Select (assembled)
└── SelectRoot
    ├── SelectTrigger
    │   ├── SelectIcon (optional slot)
    │   ├── SelectValue
    │   ├── SelectInput (when searchable)
    │   ├── SelectTrailingIcon
    │   └── SelectClear (when clearable)
    └── SelectPopover
        └── SelectListbox
            ├── SelectNoOptions
            ├── SelectOption (×N, from options prop)
            └── SelectCreateItem (when createItem is set)
```

The assembled component wires every slot and prop to the matching primitive. See [Slots](https://vue3-select-component.vercel.app/api/slots) for the mapping.

## What SelectRoot provides

`SelectRoot` is the only place that holds select state. It runs two composables:

| Layer                 | Role                                                                              |
| --------------------- | --------------------------------------------------------------------------------- |
| `useSelectCollection` | Merges options from the `options` prop and declarative `SelectOption` children    |
| `useSelectState`      | Owns `v-model`, open state, search, filtering, keyboard navigation, and selection |

The result is injected as `SelectContext`. Every primitive calls `injectSelectContext()` to read or update shared state. Primitives outside `SelectRoot` throw at runtime.

Relevant context fields:

- **Selection**: `modelValue`, `select`, `deselect`, `clear`
- **Menu**: `isOpen`, `open`, `close`, `toggle`
- **Search**: `searchValue`, `filteredOptions`
- **Keyboard**: `activeOptionValue`, `moveActiveOption`, `handleKeydown`
- **DOM refs**: `registerTriggerElement`, `registerInputElement`, and IDs for ARIA wiring

Assembled `Select` passes behavior props (`multiple`, `searchable`, `filterBy`, and the rest) straight to `SelectRoot`. It does not reimplement any of this logic.

## Assembled layer glue

### Option normalization

Your `options` prop can use any shape when you pass `getOptionValue` and `getOptionLabel`. Assembled `Select` normalizes them to `{ label, value, disabled? }[]` before passing them to `SelectRoot`.

It also renders one `SelectOption` per normalized entry. That keeps keyboard navigation, filtering, and ARIA in sync with what you passed in.

### filterBy adapter

On primitives, `filterBy` receives a registered option and the search string. On assembled `Select`, `filterBy` receives your **source** option object, its label, and the search string.

The adapter maps values back to source objects so custom filters work with your data model without touching `SelectRoot`.

### Event payloads

`SelectRoot` emits raw values on `@option-selected` and `@option-deselected`. Assembled `Select` looks up the matching source object and re-emits it as `@option-selected` / `@option-deselected`.

This matches v0 behavior and keeps TypeScript tied to your option type.

### Attribute forwarding

Assembled `Select` sets `inheritAttrs: false` and splits fallthrough attributes:

| Attribute group                            | Searchable (`true`, default) | Non-searchable  |
| ------------------------------------------ | ---------------------------- | --------------- |
| `id`, `name`, `form`, `required`, `aria-*` | `SelectInput`                | `SelectTrigger` |
| Everything else                            | `SelectRoot`                 | `SelectRoot`    |

The focusable control owns labelling attributes. See [Accessibility](https://vue3-select-component.vercel.app/guide/accessibility#label-your-select) for examples.

### Popover props

Props that belong to positioning and teleport (`teleport`, `side`, `align`, and other [reka-ui Popover](https://reka-ui.com/docs/components/popover){rel="&#x22;nofollow&#x22;"} options) are stripped from root props and forwarded to `SelectPopover`.

Search and filtering follow the same path. Typing updates `searchValue` in context. `filteredOptions` recomputes. `SelectListbox` only shows options that pass the filter.

## Defaults

These are assembled-only conveniences. Primitives do not implement them.

| Feature       | Assembled default                         | Primitive equivalent                                     |
| ------------- | ----------------------------------------- | -------------------------------------------------------- |
| Search        | `searchable: true`                        | Add `SelectInput`, pass `searchable` to `SelectRoot`     |
| Options list  | `v-for` over normalized options           | Render `SelectOption` yourself or rely on `options` prop |
| Empty state   | `SelectNoOptions` wired                   | Add `SelectNoOptions` in your listbox                    |
| Clear button  | `clearable` prop + `SelectClear`          | Render `SelectClear` when needed                         |
| Create option | `createItem` prop + `SelectCreateItem`    | Add `SelectCreateItem` manually                          |
| Styles        | `data-assembled-select` + import `styles` | Use `data-select-*` hooks on each primitive              |

## When to drop to primitives

Stay on assembled `Select` when the default trigger, listbox, and popover layout fit your product.

Reach for primitives when you need to:

- Change DOM structure (infinite scroll, virtual lists, custom groups)
- Own open state or popover rendering
- Emit raw values instead of source objects
- Skip option normalization and register options only via children

Start from the [Primitives](https://vue3-select-component.vercel.app/guide/primitives) guide or the [examples](https://vue3-select-component.vercel.app/guide/examples#primitives) page. Copy the assembled tree and replace the pieces you need.

## Related reading

- [Primitives](https://vue3-select-component.vercel.app/guide/primitives) for the component tree and option registration
- [Usage](https://vue3-select-component.vercel.app/getting-started/usage) for day-to-day assembled `Select` setup
- [Components reference](https://vue3-select-component.vercel.app/api/components) for per-primitive props and DOM hooks
- [Styling](https://vue3-select-component.vercel.app/guide/styling) for `data-assembled-select` and CSS variables


# Props

## Assembled Select

The default export from `vue3-select-component`.

::note
v0 boolean prop names (

`isMulti`

, 

`isSearchable`

, etc.) are not supported. Rename them to v1 names when upgrading. See the 

[migration guide](https://vue3-select-component.vercel.app/guide/migration)

.
::

### v-model

|              |                                                                    |
| ------------ | ------------------------------------------------------------------ |
| **Type**     | `string | number | null` (single) or `(string | number)[]` (multi) |
| **Required** | No                                                                 |
| **Default**  | `null` (single) / `[]` (multi)                                     |

The selected value(s). Type must match `option.value`. See [TypeScript](https://vue3-select-component.vercel.app/guide/typescript).

### options

|              |                   |
| ------------ | ----------------- |
| **Type**     | `GenericOption[]` |
| **Required** | Yes               |

List of options. Each option needs `label` and `value` unless custom mappers are provided.

```ts
type SelectOptionData<Value extends string | number> = {
  label: string
  value: Value
  disabled?: boolean
}
```

### placeholder

|             |             |
| ----------- | ----------- |
| **Type**    | `string`    |
| **Default** | `undefined` |

Text shown when no option is selected. Passed to `SelectValue`.

### multiple

|             |           |
| ----------- | --------- |
| **Type**    | `boolean` |
| **Default** | `false`   |

Allow multiple selections. `v-model` must be an array.

### closeOnSelect

|             |                  |
| ----------- | ---------------- |
| **Type**    | `boolean | null` |
| **Default** | `null`           |

Control whether the menu closes after a selection. When `null` (default), the menu closes on single-select and stays open on multi-select. Set to `true` or `false` to override.

### resetSearchOnBlur

|             |           |
| ----------- | --------- |
| **Type**    | `boolean` |
| **Default** | `true`    |

Clear the search input when the menu closes (blur or dismiss). Set to `false` to keep the query when reopening the menu.

### resetSearchOnSelect

|             |           |
| ----------- | --------- |
| **Type**    | `boolean` |
| **Default** | `true`    |

Clear the search input after an option is selected. Set to `false` to keep filtering while picking multiple values.

### hideSelected

|             |           |
| ----------- | --------- |
| **Type**    | `boolean` |
| **Default** | `false`   |

When `multiple` is enabled, remove already-selected options from the dropdown list. Selected values remain as tags in the trigger. Has no effect in single-select mode.

```vue [App.vue]
<script setup lang="ts">
import { ref } from "vue"
import Select from "vue3-select-component"
import "vue3-select-component/styles"

const selected = ref<string[]>(["js"])

const options = [
  { label: "JavaScript", value: "js" },
  { label: "TypeScript", value: "ts" },
  { label: "Vue", value: "vue" },
]
</script>

<template>
  <Select
    v-model="selected"
    multiple
    hide-selected
    :options="options"
    placeholder="Select languages"
  />
</template>
```

### searchable

|             |           |
| ----------- | --------- |
| **Type**    | `boolean` |
| **Default** | `true`    |

Show a search input in the trigger to filter options. Set `:searchable="false"` to disable it.

### clearable

|             |           |
| ----------- | --------- |
| **Type**    | `boolean` |
| **Default** | `false`   |

Show a clear button when a value is selected.

### disabled

|             |           |
| ----------- | --------- |
| **Type**    | `boolean` |
| **Default** | `false`   |

Disable all interaction.

### loading

|             |           |
| ----------- | --------- |
| **Type**    | `boolean` |
| **Default** | `false`   |

Expose loading state to `SelectTrailingIcon` via `data-loading`.

### Popover props

The assembled `Select` forwards [reka-ui](https://reka-ui.com/docs/components/popover){rel="&#x22;nofollow&#x22;"} popover props to the internal `SelectPopover`. Use them to control placement, collision behavior, modality, and teleport deferral.

| Prop                          | Type                                     | Default     | Maps to                             |
| ----------------------------- | ---------------------------------------- | ----------- | ----------------------------------- |
| `teleport`                    | `boolean | string | HTMLElement`         | `true`      | `PopoverPortal` (`to` / `disabled`) |
| `defer`                       | `boolean`                                | `undefined` | `PopoverPortal`                     |
| `modal`                       | `boolean`                                | `undefined` | `PopoverRoot`                       |
| `side`                        | `'top' | 'right' | 'bottom' | 'left'`    | `'bottom'`  | `PopoverContent`                    |
| `sideOffset`                  | `number`                                 | `4`         | `PopoverContent`                    |
| `sideFlip`                    | `boolean`                                | `undefined` | `PopoverContent`                    |
| `align`                       | `'start' | 'center' | 'end'`             | `'start'`   | `PopoverContent`                    |
| `alignOffset`                 | `number`                                 | `undefined` | `PopoverContent`                    |
| `alignFlip`                   | `boolean`                                | `undefined` | `PopoverContent`                    |
| `avoidCollisions`             | `boolean`                                | `true`      | `PopoverContent`                    |
| `collisionBoundary`           | `Element | null | Element[]`             | `undefined` | `PopoverContent`                    |
| `collisionPadding`            | `number | Partial<Record<Side, number>>` | `undefined` | `PopoverContent`                    |
| `arrowPadding`                | `number`                                 | `undefined` | `PopoverContent`                    |
| `hideShiftedArrow`            | `boolean`                                | `undefined` | `PopoverContent`                    |
| `sticky`                      | `'partial' | 'always'`                   | `undefined` | `PopoverContent`                    |
| `hideWhenDetached`            | `boolean`                                | `undefined` | `PopoverContent`                    |
| `positionStrategy`            | `'absolute' | 'fixed'`                   | `undefined` | `PopoverContent`                    |
| `updatePositionStrategy`      | `'optimized' | 'always'`                 | `undefined` | `PopoverContent`                    |
| `disableUpdateOnLayoutShift`  | `boolean`                                | `undefined` | `PopoverContent`                    |
| `prioritizePosition`          | `boolean`                                | `undefined` | `PopoverContent`                    |
| `disableOutsidePointerEvents` | `boolean`                                | `undefined` | `PopoverContent`                    |

`teleport` controls where the panel is rendered. `true` (default) teleports to `body`. A string is a CSS selector target. An `HTMLElement` teleports to that element. Set to `false` to render inline.

`open`, anchor `reference`, and `forceMount` are managed internally and are not exposed.

```vue [App.vue]
<script setup lang="ts">
import { ref } from "vue"
import Select from "vue3-select-component"
import "vue3-select-component/styles"

const value = ref<string | null>(null)

const options = [
  { label: "Option #1", value: "option_1" },
  { label: "Option #2", value: "option_2" },
  { label: "Option #3", value: "option_3" },
]
</script>

<template>
  <Select
    v-model="value"
    :options="options"
    side="top"
    :side-offset="8"
    align="end"
    placeholder="Open to inspect placement"
  />
</template>
```

### getOptionLabel

|             |                                     |
| ----------- | ----------------------------------- |
| **Type**    | `(option: GenericOption) => string` |
| **Default** | `option => option.label`            |

Extract the display label from a custom option shape.

### getOptionValue

|             |                                              |
| ----------- | -------------------------------------------- |
| **Type**    | `(option: GenericOption) => string | number` |
| **Default** | `option => option.value`                     |

Extract the value from a custom option shape.

### filterBy

|             |                                        |
| ----------- | -------------------------------------- |
| **Type**    | `(option, label, search) => boolean`   |
| **Default** | Case-insensitive label substring match |

Custom filter for searchable mode. Receives the **source** option object.

### createItem

|             |                      |
| ----------- | -------------------- |
| **Type**    | `boolean | "always"` |
| **Default** | `undefined`          |

Allow users to create a custom value from the current search query. Requires `searchable="true"`.

Listen to `@create` and update your options and `v-model`.

- `true`: show the create action only when filtering leaves no matches.
- `"always"`: show the create action whenever the search query is non-empty, even if options still match.

```vue [App.vue]
<script setup lang="ts">
import { ref } from "vue"
import Select from "vue3-select-component"
import "vue3-select-component/styles"

const value = ref<string | null>(null)
const items = ref<{ label: string; value: string }[]>([])

function onCreate(query: string) {
  const newItem = { label: query, value: query }
  items.value.push(newItem)
  value.value = newItem.value
}
</script>

<template>
  <Select
    v-model="value"
    :create-item="true"
    :options="items"
    placeholder="Type to create an item"
    @create="onCreate"
  />
</template>
```

---

## SelectRoot

Props for the primitive root component (`vue3-select-component/primitives`).

| Prop                  | Type                        | Default         | Description                                         |
| --------------------- | --------------------------- | --------------- | --------------------------------------------------- |
| `v-model`             | `SelectModelValue<Value>`   | `null`          | Selected value(s)                                   |
| `options`             | `SelectOptionData<Value>[]` | `[]`            | Normalized options array                            |
| `multiple`            | `boolean`                   | `false`         | Multi-select mode                                   |
| `searchable`          | `boolean`                   | `false`         | Enable trigger search input                         |
| `clearable`           | `boolean`                   | `false`         | Show clear button                                   |
| `disabled`            | `boolean`                   | `false`         | Disable interaction                                 |
| `loading`             | `boolean`                   | `false`         | Loading state                                       |
| `closeOnSelect`       | `boolean | null`            | `null`          | Close menu after selection (`null` = auto)          |
| `resetSearchOnBlur`   | `boolean`                   | `true`          | Clear search when the menu closes                   |
| `resetSearchOnSelect` | `boolean`                   | `true`          | Clear search after an option is selected            |
| `hideSelected`        | `boolean`                   | `false`         | Hide selected options from the list in multi-select |
| `createItem`          | `boolean | "always"`        | `undefined`     | Allow creating a value from the search query        |
| `filterBy`            | `FilterByFn<Value>`         | Label substring | Custom filter on registered options                 |

---

## Primitive props

### SelectValue

| Prop          | Type     | Default |
| ------------- | -------- | ------- |
| `placeholder` | `string` |         |

### SelectOption

| Prop       | Type              | Default      |
| ---------- | ----------------- | ------------ |
| `value`    | `string | number` | **required** |
| `label`    | `string`          | **required** |
| `disabled` | `boolean`         | `false`      |

### SelectTag

| Prop    | Type              | Default      |
| ------- | ----------------- | ------------ |
| `value` | `string | number` | **required** |
| `label` | `string`          | **required** |

### SelectPopover

`SelectPopover` forwards [reka-ui](https://reka-ui.com/docs/components/popover){rel="&#x22;nofollow&#x22;"} `PopoverRoot`, `PopoverPortal`, and `PopoverContent` props. See the assembled [Popover props](https://vue3-select-component.vercel.app/#popover-props) table for the full list.

| Prop              | Type                                  | Default    |
| ----------------- | ------------------------------------- | ---------- |
| `teleport`        | `boolean | string | HTMLElement`      | `true`     |
| `side`            | `'top' | 'right' | 'bottom' | 'left'` | `'bottom'` |
| `align`           | `'start' | 'center' | 'end'`          | `'start'`  |
| `sideOffset`      | `number`                              | `4`        |
| `avoidCollisions` | `boolean`                             | `true`     |

All other supported popover props from the table above are also available on `SelectPopover`. Content emits (`escapeKeyDown`, `pointerDownOutside`, `focusOutside`, `interactOutside`, `openAutoFocus`, `closeAutoFocus`) can be listened to on `SelectPopover`.

`SelectTrigger`, `SelectListbox`, `SelectClear`, `SelectCreateItem`, `SelectIcon`, `SelectTrailingIcon`, and `SelectNoOptions` accept no props. `SelectInput` accepts optional `id` and `placeholder` props.


# Events

## Assembled Select events

### optionSelected

Emitted when an option is selected, in the same tick as the `v-model` update.

|             |                                               |
| ----------- | --------------------------------------------- |
| **Payload** | `GenericOption`, the **source** option object |

```vue
<Select
  v-model="selected"
  :options="options"
  @option-selected="(option) => console.log(option.label, option.value)"
/>
```

::tip
For tracking the current selection, prefer a `computed` derived from `v-model` over listening to this event:

```ts
const selectedOption = computed(() =>
  options.find((o) => o.value === selected.value),
)
```
::

### optionDeselected

Emitted when an option is deselected.

|             |                        |
| ----------- | ---------------------- |
| **Payload** | `GenericOption | null` |

`null` is emitted when clearing all values in multi-select mode.

```vue
<Select
  v-model="selected"
  :options="options"
  @option-deselected="(option) => console.log(option)"
/>
```

::note
Pressing 

**Backspace**

 to remove the last tag in multi-select updates 

`v-model`

 but does 

**not**

 emit 

`optionDeselected`

.
::

### search

Emitted when the search value changes in searchable mode.

|             |          |
| ----------- | -------- |
| **Payload** | `string` |

```vue
<Select
  v-model="selected"
  :options="options"
  @search="(query) => fetchRemoteOptions(query)"
/>
```

### menuOpened

Emitted when the dropdown menu opens.

```vue
<Select @menu-opened="onMenuOpened" />
```

### menuClosed

Emitted when the dropdown menu closes.

```vue
<Select @menu-closed="onMenuClosed" />
```

### create

Emitted when the user chooses to create a new item from the search query. Requires `create-item`. The component does not update `options` or `v-model` for you. Handle the event and update your data.

|             |                                    |
| ----------- | ---------------------------------- |
| **Payload** | `string`, the trimmed search query |

```vue [App.vue]
<script setup lang="ts">
import { ref } from "vue"
import Select from "vue3-select-component"
import "vue3-select-component/styles"

const items = ref(["Backlog", "Todo", "Done"])
const value = ref("Backlog")

function onCreate(item: string) {
  items.value.push(item)
  value.value = item
}
</script>

<template>
  <Select
    v-model="value"
    create-item
    :options="items"
    :get-option-label="(item) => item"
    :get-option-value="(item) => item"
    placeholder="Pick or create a status"
    @create="onCreate"
  />
</template>
```

---

## SelectRoot events

Primitive root emits the same lifecycle events with different selection payloads:

| Event               | Payload                   | Notes                        |
| ------------------- | ------------------------- | ---------------------------- |
| `update:modelValue` | `SelectModelValue<Value>` | Use with `v-model`           |
| `optionSelected`    | `OptionValue`             | Raw value, not source object |
| `optionDeselected`  | `OptionValue | null`      | `null` on multi clear-all    |
| `search`            | `string`                  | Search text changed          |
| `create`            | `string`                  | Create-item action chosen    |
| `menuOpened`        |                           | Menu opened                  |
| `menuClosed`        |                           | Menu closed                  |

```vue [CustomSelect.vue]
<script setup lang="ts">
import { ref } from "vue"
import {
  SelectListbox,
  SelectNoOptions,
  SelectOption,
  SelectPopover,
  SelectRoot,
  SelectTrigger,
  SelectValue,
} from "vue3-select-component/primitives"
import "vue3-select-component/styles"

const model = ref<string | null>(null)

const options = [
  { label: "JavaScript", value: "js" },
  { label: "TypeScript", value: "ts" },
]

function onOptionSelected(value: string) {
  console.log(value)
}
</script>

<template>
  <div data-assembled-select>
    <SelectRoot
      v-model="model"
      :options="options"
      @option-selected="onOptionSelected"
    >
      <SelectTrigger>
        <SelectValue placeholder="Pick a language" />
      </SelectTrigger>

      <SelectPopover>
        <SelectListbox>
          <SelectNoOptions />
          <SelectOption
            v-for="option in options"
            :key="option.value"
            :value="option.value"
            :label="option.label"
          />
        </SelectListbox>
      </SelectPopover>
    </SelectRoot>
  </div>
</template>
```


# Slots

::info
The assembled 

`Select`

 exposes 

`icon`

, 

`trailing-icon`

, 

`tag-remove`

, 

`no-options`

, 

`create-item`

, and 

`clear`

 slots. Enable the clear button with the 

`clearable`

 prop. For broader customization, compose with 

[primitives](https://vue3-select-component.vercel.app/guide/primitives)

.
::

Primitives expose slots for flexible rendering. `SelectRoot`, `SelectTrigger`, `SelectPopover`, and `SelectListbox` also accept a `default` slot for structural composition.

## Assembled Select

The assembled `Select` forwards customization slots to the underlying primitives.

**`tag-remove`**: remove button content for each tag in multi-select mode.

**Slot props:** `SelectTagRemoveSlotProps`

```ts
{ label: string; value: string | number }
```

```vue
<Select v-model="selected" multiple :options="options">
  <template #tag-remove="{ label }">
    <UIcon name="i-lucide-x" :aria-label="`Remove ${label}`" />
  </template>
</Select>
```

**`no-options`**: empty state when search or filtering removes every option.

**Slot props:** `SelectSearchValueSlotProps`

```vue
<Select v-model="selected" :options="options">
  <template #no-options="{ searchValue }">
    No results for "{{ searchValue }}"
  </template>
</Select>
```

**`create-item`**: create action shown when `create-item` is enabled. Receives the trimmed search query.

**Slot props:** `SelectSearchValueSlotProps`

```vue
<Select v-model="value" create-item :options="items" @create="onCreate">
  <template #create-item="{ searchValue }">
    Add "{{ searchValue }}"
  </template>
</Select>
```

**`clear`**: clear button content. Requires `clearable`.

```vue
<Select v-model="selected" clearable :options="options">
  <template #clear>
    Reset
  </template>
</Select>
```

**`icon`**: leading icon before the placeholder or selected value.

```vue
<Select v-model="selected" :options="options" placeholder="Select a country">
  <template #icon>
    <UIcon name="i-lucide-globe" />
  </template>
</Select>
```

**`trailing-icon`**: trailing dropdown icon. Receives open and loading state.

**Slot props:** `SelectTrailingIconSlotProps`

```ts
{ open: boolean; loading: boolean }
```

```vue
<Select v-model="selected" :options="options">
  <template #trailing-icon="{ open, loading }">
    <span v-if="loading">⏳</span>
    <span v-else-if="open">▲</span>
    <span v-else>▼</span>
  </template>
</Select>
```

## Primitives

### SelectValue

Customize how the selected value is displayed.

**Slot props:** `SelectValueDefaultSlotProps<OptionValue>`

```ts
{
  selectedOptions: readonly {
    id: string
    value: OptionValue
    label: string
    disabled: boolean
  }[]
}
```

```vue
<SelectValue placeholder="Pick one">
  <template #default="{ selectedOptions }">
    <span v-if="selectedOptions[0]">
      ✓ {{ selectedOptions[0].label }}
    </span>
    <span v-else class="placeholder">Pick one</span>
  </template>
</SelectValue>
```

Default behavior: single mode shows the first label or placeholder. Multi mode renders `SelectTag` per selection.

**Named slot `tag-remove`:** remove button content for each tag in multi-select mode. Forwards to `SelectTag`'s `remove` slot.

```vue
<SelectValue placeholder="Pick languages">
  <template #tag-remove="{ label }">
    Remove {{ label }}
  </template>
</SelectValue>
```

### SelectOption

Customize option content in the listbox.

```vue
<SelectOption :value="opt.value" :label="opt.label">
  <strong>{{ opt.label }}</strong>
  <span class="text-muted">{{ opt.description }}</span>
</SelectOption>
```

**Named slot `checkmark`:** icon shown on the right when the option is selected in multi-select mode. Only rendered when `multiple` is enabled and the option is selected.

```vue
<SelectOption :value="opt.value" :label="opt.label">
  <template #checkmark>
    <UIcon name="i-lucide-check" />
  </template>
</SelectOption>
```

### SelectGroup and SelectGroupLabel

::note
You do not need group primitives for a flat list. Render 

`SelectOption`

 children directly inside 

`SelectListbox`

.
::

```vue
<SelectGroup>
  <SelectGroupLabel>Frontend</SelectGroupLabel>
  <SelectOption value="vue" label="Vue" />
  <SelectOption value="react" label="React" />
</SelectGroup>
```

Both components use a plain `default` slot. `SelectGroupLabel` must be inside `SelectGroup`.

### SelectSeparator

Insert a non-interactive divider between groups or sections.

```vue
<SelectGroup>
  <SelectGroupLabel>Europe</SelectGroupLabel>
  <SelectOption value="FR" label="France" />
  <SelectOption value="DE" label="Germany" />
  <SelectOption value="IT" label="Italy" />
</SelectGroup>

<SelectSeparator />
```

### SelectTag

Customize multi-value tags. Used by `SelectValue` in multi-select mode.

**Default slot props:** `SelectTagRemoveSlotProps`

```ts
{ label: string; value: string | number }
```

**Named slot `remove`:** content for the remove button (default: × icon). Uses the same `SelectTagRemoveSlotProps` shape.

```vue
<SelectTag :value="opt.value" :label="opt.label">
  <template #default="{ label }">
    <span class="tag-label">{{ label }}</span>
  </template>
  <template #remove>
    ×
  </template>
</SelectTag>
```

The remove button calls `context.deselect(value)` and has `aria-label="Remove"`.

### SelectIcon

Leading icon before the value display. Place inside `SelectTrigger`, before `SelectValue`.

```vue
<SelectTrigger>
  <SelectIcon>
    <UIcon name="i-lucide-globe" />
  </SelectIcon>
  <SelectValue placeholder="Pick one" />
  <SelectTrailingIcon />
</SelectTrigger>
```

Rendered with `data-select-icon` and `aria-hidden="true"`.

### SelectTrailingIcon

Trailing dropdown icon for open and loading state.

**Slot props:** `SelectTrailingIconSlotProps`

```ts
{ open: boolean; loading: boolean }
```

```vue
<SelectTrailingIcon>
  <template #default="{ open, loading }">
    <span v-if="loading">⏳</span>
    <span v-else-if="open">▲</span>
    <span v-else>▼</span>
  </template>
</SelectTrailingIcon>
```

Exposed via `data-open` and `data-loading` attributes for CSS-only styling.

### SelectCreateItem

Customize the create action when `create-item` is enabled on `SelectRoot`.

**Slot props:** `SelectSearchValueSlotProps`

```ts
{ searchValue: string }
```

```vue
<SelectRoot v-model="model" create-item searchable :options="options" @create="onCreate">
  <SelectPopover>
    <SelectListbox>
      <SelectOption v-for="option in options" :key="option.value" v-bind="option" />
      <SelectCreateItem>
        <template #default="{ searchValue }">
          Create "{{ searchValue }}"
        </template>
      </SelectCreateItem>
    </SelectListbox>
  </SelectPopover>
</SelectRoot>
```

Default text: `Create "{searchValue}"`. Renders with `role="option"` when visible.

### SelectNoOptions

Customize the empty state when no options match the search filter.

**Slot props:** `SelectSearchValueSlotProps`

```ts
{ searchValue: string }
```

```vue
<SelectNoOptions>
  <template #default="{ searchValue }">
    No languages found for "{{ searchValue }}".
  </template>
</SelectNoOptions>
```

Default text: `"No options"`. Renders with `role="status"` when `filteredOptions` is empty.

### SelectClear

Customize the clear button content. Place inside `SelectTrigger` and enable with `clearable` on `SelectRoot`.

```vue
<SelectRoot v-model="model" clearable :options="options">
  <SelectTrigger>
    <SelectValue placeholder="Pick one" />
    <SelectClear>Reset</SelectClear>
  </SelectTrigger>
</SelectRoot>
```

Visible only when `clearable` is enabled, a value exists, and the select is not disabled. Has `data-select-clear` and `aria-label="Clear selection"`.

### SelectTrigger, SelectInput, SelectListbox, SelectPopover

These accept a `default` slot for child composition but do not expose scoped slot props.

```vue
<SelectTrigger>
  <SelectIcon>
    <UIcon name="i-lucide-globe" />
  </SelectIcon>
  <SelectValue placeholder="Choose" />
  <SelectTrailingIcon />
</SelectTrigger>
```

## TypeScript

Slot names and scoped prop types are exported from `vue3-select-component` for wrappers and custom compositions.

**Assembled `Select`:**

```ts
import type { AssembledSelectSlots } from "vue3-select-component"
```

**Primitives:**

```ts
import type {
  SelectClearSlots,
  SelectCreateItemSlots,
  SelectDefaultSlots,
  SelectGroupLabelSlots,
  SelectGroupSlots,
  SelectIconSlots,
  SelectNoOptionsSlots,
  SelectOptionSlots,
  SelectSeparatorSlots,
  SelectTagSlots,
  SelectTrailingIconSlots,
  SelectValueSlots,
} from "vue3-select-component"
```

**Reusable slot prop types:**

```ts
import type {
  SelectSearchValueSlotProps,
  SelectTagRemoveSlotProps,
  SelectTrailingIconSlotProps,
  SelectValueDefaultSlotProps,
} from "vue3-select-component"
```

`SelectValueSlots` and `SelectValueDefaultSlotProps` accept an optional `OptionValue` generic. `tag-remove` slot props use `value: string | number` so forwarded slots type-check across generic components.

See [TypeScript](https://vue3-select-component.vercel.app/guide/typescript) for props, emits, and model value types.


# Components

All primitives are exported from `vue3-select-component/primitives` and must be used inside `SelectRoot`.

## SelectRoot

State provider and context source. Manages `v-model`, open state, search, filtering, keyboard navigation, and option registration.

|           |                                                                                     |
| --------- | ----------------------------------------------------------------------------------- |
| **Props** | See [Props](https://vue3-select-component.vercel.app/api/props#selectroot)          |
| **Emits** | See [Events](https://vue3-select-component.vercel.app/api/events#selectroot-events) |
| **Slots** | `default`, trigger and popover composition                                          |
| **DOM**   | `data-select-root`                                                                  |

## SelectTrigger

The interactive trigger area that toggles the menu. It renders as a button when not searchable and as a layout wrapper when searchable.

|           |                                                                                                                                                |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| **Props** | None                                                                                                                                           |
| **Slots** | `default`, typically `SelectIcon`, `SelectValue`, `SelectInput`, `SelectTrailingIcon`, `SelectClear`                                           |
| **DOM**   | `data-select-trigger`                                                                                                                          |
| **ARIA**  | Button mode: `aria-expanded`, `aria-haspopup="listbox"`, `aria-controls`. Searchable mode: layout only; combobox ARIA belongs to `SelectInput` |

## SelectValue

Displays the current selection or placeholder.

|           |                                                                    |
| --------- | ------------------------------------------------------------------ |
| **Props** | `placeholder?: string`                                             |
| **Slots** | `default`, `{ selectedOptions }`, `tag-remove`, `{ label, value }` |
| **DOM**   | `data-select-value`, `data-empty`                                  |

## SelectInput

Search input rendered when `searchable` is enabled. In the assembled layout it lives inside `SelectTrigger`.

|           |                                                                                                                                     |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| **Props** | `id?: string`, `placeholder?: string`                                                                                               |
| **DOM**   | `data-select-input`                                                                                                                 |
| **ARIA**  | `role="combobox"`, `aria-autocomplete="list"`, `aria-haspopup="listbox"`, `aria-expanded`, `aria-controls`, `aria-activedescendant` |
| **Notes** | `autocomplete="off"`, bound to context search value                                                                                 |

## SelectPopover

Dropdown panel container built on reka-ui `Popover`. Supports teleporting and forwards reka-ui popover props for placement, collision handling, and modality. See [Popover props](https://vue3-select-component.vercel.app/api/props#popover-props).

|           |                                                                                                                                                                           |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Props** | `teleport`, `side`, `align`, `sideOffset`, `modal`, `defer`, and other [reka-ui `PopoverContent` props](https://vue3-select-component.vercel.app/api/props#popover-props) |
| **Emits** | `escapeKeyDown`, `pointerDownOutside`, `focusOutside`, `interactOutside`, `openAutoFocus`, `closeAutoFocus`                                                               |
| **Slots** | `default`, usually `SelectListbox`                                                                                                                                        |
| **DOM**   | `data-select-popover`                                                                                                                                                     |
| **ARIA**  | `aria-hidden` when closed                                                                                                                                                 |

## SelectListbox

Container for options with `role="listbox"`.

|           |                                                                              |
| --------- | ---------------------------------------------------------------------------- |
| **Props** | None                                                                         |
| **Slots** | `default`, `SelectOption` and `SelectNoOptions`                              |
| **DOM**   | `data-select-listbox`                                                        |
| **ARIA**  | `role="listbox"`, `aria-labelledby`, `aria-multiselectable`, `tabindex="-1"` |

## SelectOption

A single selectable option. Registers with context on mount.

|           |                                                                                                               |
| --------- | ------------------------------------------------------------------------------------------------------------- |
| **Props** | `value`, `label`, `disabled?`                                                                                 |
| **Slots** | `default`, `checkmark`                                                                                        |
| **DOM**   | `data-select-option`, `data-select-option-label`, `data-select-option-checkmark`, `data-value`, `data-active` |
| **ARIA**  | `role="option"`, `aria-selected`, `aria-disabled`                                                             |

Hidden when filtered out by search or when `hideSelected` removes selected values in multi-select. In multi-select mode, selected options show a default checkmark icon on the right (overridable via the `checkmark` slot). Click calls `context.select(value)`.

## SelectGroup

Use when options need labelled sections. For a flat list, render `SelectOption` directly inside `SelectListbox`.

Structural wrapper for related options. It is not selectable and does not register in the option collection.

|           |                                                           |
| --------- | --------------------------------------------------------- |
| **Props** | None                                                      |
| **Slots** | `default`, usually `SelectGroupLabel` and `SelectOption`  |
| **DOM**   | `data-select-group`                                       |
| **ARIA**  | `role="group"`, `aria-labelledby` when a label is present |

The group hides when filtering removes all of its child options.

## SelectGroupLabel

Label for a `SelectGroup`.

|           |                           |
| --------- | ------------------------- |
| **Props** | None                      |
| **Slots** | `default`                 |
| **DOM**   | `data-select-group-label` |

Must be rendered inside `SelectGroup`.

## SelectSeparator

Optional. Use with grouped lists when you need a visual break between sections.

Visual separator between option groups or option sections.

|           |                                                     |
| --------- | --------------------------------------------------- |
| **Props** | None                                                |
| **Slots** | None                                                |
| **DOM**   | `data-select-separator`                             |
| **ARIA**  | `role="separator"`, `aria-orientation="horizontal"` |

## SelectTag

Chip for a selected value in multi-select mode.

|           |                                                             |
| --------- | ----------------------------------------------------------- |
| **Props** | `value`, `label`                                            |
| **Slots** | `default`, `{ label, value }`, `remove`, `{ label, value }` |
| **DOM**   | `data-select-tag`, `data-select-tag-remove`                 |

## SelectClear

Button to reset the selection.

|           |                                |
| --------- | ------------------------------ |
| **Props** | None                           |
| **Slots** | `default`                      |
| **DOM**   | `data-select-clear`            |
| **ARIA**  | `aria-label="Clear selection"` |

Visible when `clearable && hasValue && !disabled`.

## SelectIcon

Leading icon before the value display.

|           |                      |
| --------- | -------------------- |
| **Props** | None                 |
| **Slots** | `default`            |
| **DOM**   | `data-select-icon`   |
| **ARIA**  | `aria-hidden="true"` |

## SelectTrailingIcon

Trailing dropdown icon for open/loading state.

|           |                                                          |
| --------- | -------------------------------------------------------- |
| **Props** | None                                                     |
| **Slots** | `default`, `{ open, loading }`                           |
| **DOM**   | `data-select-trailing-icon`, `data-open`, `data-loading` |
| **ARIA**  | `aria-hidden="true"`                                     |

## SelectCreateItem

Create action for custom values from the search query. Requires `create-item` on `SelectRoot`.

|           |                              |
| --------- | ---------------------------- |
| **Props** | None                         |
| **Slots** | `default`, `{ searchValue }` |
| **DOM**   | `data-select-create-item`    |
| **ARIA**  | `role="option"`              |

## SelectNoOptions

Empty state when no options match the filter.

|           |                              |
| --------- | ---------------------------- |
| **Props** | None                         |
| **Slots** | `default`, `{ searchValue }` |
| **DOM**   | `data-select-no-options`     |
| **ARIA**  | `role="status"`              |

## Assembled Select

Fixed composition of all primitives. See [Usage](https://vue3-select-component.vercel.app/getting-started/usage), [Assembled Select deep dive](https://vue3-select-component.vercel.app/guide/deep-dive), and [Props](https://vue3-select-component.vercel.app/api/props#assembled-select).

|            |                                                                                                                                                                           |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Import** | `import Select from "vue3-select-component"`                                                                                                                              |
| **Slots**  | `icon`, `trailing-icon`, `{ open, loading }`, `tag-remove`, `{ label, value }` (multi-select), `no-options`, `{ searchValue }`, `create-item`, `{ searchValue }`, `clear` |
| **Props**  | Includes `clearable` to show the clear button                                                                                                                             |
| **DOM**    | `data-assembled-select` on root                                                                                                                                           |

**Default structure:**

```text
SelectRoot
├── SelectTrigger
│   ├── SelectIcon
│   ├── SelectValue
│   ├── SelectInput
│   ├── SelectTrailingIcon
│   └── SelectClear
└── SelectPopover
    └── SelectListbox
        ├── SelectNoOptions
        ├── SelectGroup
        │   ├── SelectGroupLabel
        │   └── SelectOption (per option)
        ├── SelectSeparator
        ├── SelectOption (per option)
        └── SelectCreateItem (when create-item is enabled)
```


# Vue 3 Select Component

::u-page-hero
---
ui:
  container: max-w-7xl mx-auto
orientation: vertical
---
#headline
  :::u-button
  ---
  icon: i-lucide-sparkles
  size: md
  to: https://vue3-select-component.vercel.app/guide/migration
  variant: soft
  ---
  v1: introducing Primitives
  :::

#title
Vue 3 Select Component

#description
Ship accessible selects in minutes. Use the assembled component or compose headless primitives.

#links
  :::u-button
  ---
  color: neutral
  size: xl
  to: https://vue3-select-component.vercel.app/getting-started/introduction
  trailing-icon: i-lucide-arrow-right
  ---
  Get Started
  :::

  :::u-button
  ---
  color: neutral
  icon: i-simple-icons-github
  size: xl
  target: _blank
  to: https://github.com/TotomInc/vue3-select-component
  variant: outline
  ---
  GitHub
  :::
::

::u-page-section
---
ui:
  container: max-w-7xl mx-auto
description: Type-safe and accessible. Pick the assembled component or compose primitives.
headline: Core features
title: Everything you need in a select
---
#features
  :::u-page-feature
  ---
  icon: i-lucide-layers
  to: https://vue3-select-component.vercel.app/getting-started/usage
  ---
  #title
  Batteries-included Select

  #description
  Drop-in component with v-model, options, search, clear, and multi-select.
  :::

  :::u-page-feature
  ---
  icon: i-lucide-blocks
  to: https://vue3-select-component.vercel.app/guide/primitives
  ---
  #title
  Headless primitives

  #description
  Compose SelectRoot, SelectTrigger, SelectPopover, and more for custom UX.
  :::

  :::u-page-feature
  ---
  icon: i-lucide-braces
  to: https://vue3-select-component.vercel.app/guide/typescript
  ---
  #title
  End-to-end types

  #description
  Generics tie option values to v-model. Extend options with custom fields safely.
  :::

  :::u-page-feature
  ---
  icon: i-lucide-shield-check
  to: https://vue3-select-component.vercel.app/guide/accessibility
  ---
  #title
  Accessible by default

  #description
  WAI-ARIA combobox pattern, keyboard navigation, focus management, and screen readers.
  :::

  :::u-page-feature
  ---
  icon: i-lucide-palette
  to: https://vue3-select-component.vercel.app/guide/styling
  ---
  #title
  Your design system

  #description
  Unstyled primitives with stable data-attribute hooks. Bring your own CSS.
  :::

  :::u-page-feature
  ---
  icon: i-lucide-arrow-right-left
  to: https://vue3-select-component.vercel.app/guide/migration
  ---
  #title
  v0 migration guide

  #description
  Step-by-step upgrade path from v0 to v1. Rename props, restyle, and adopt primitives.
  :::
::

::u-page-section
---
ui:
  container: max-w-7xl mx-auto
description: Configuration, customization, and every primitive component.
headline: Documentation
title: Explore the API
---
  :::u-page-grid
    ::::u-page-card
    ---
    spotlight: true
    class: col-span-2 lg:col-span-1
    icon: i-lucide-settings-2
    to: https://vue3-select-component.vercel.app/api/props
    ---
    #title
    Props

    #description
    v-model, options, flags, mappers, teleport, and filterBy for Select and SelectRoot.
    ::::

    ::::u-page-card
    ---
    spotlight: true
    class: col-span-2 lg:col-span-1
    icon: i-lucide-zap
    to: https://vue3-select-component.vercel.app/api/events
    ---
    #title
    Events

    #description
    optionSelected, optionDeselected, search, menuOpened, and menuClosed with typed payloads.
    ::::

    ::::u-page-card
    ---
    spotlight: true
    class: col-span-2 lg:col-span-1
    icon: i-lucide-layout-template
    to: https://vue3-select-component.vercel.app/api/slots
    ---
    #title
    Slots

    #description
    Customize values, options, tags, icons, and empty states on primitives.
    ::::

    ::::u-page-card
    ---
    spotlight: true
    class: col-span-2 lg:col-span-1
    icon: i-lucide-box
    to: https://vue3-select-component.vercel.app/api/components
    ---
    #title
    Components

    #description
    Reference for SelectRoot, SelectTrigger, SelectListbox, SelectOption, and more.
    ::::

    ::::u-page-card
    ---
    spotlight: true
    class: col-span-2 lg:col-span-1
    icon: i-lucide-check-square
    to: https://vue3-select-component.vercel.app/guide/multiselect
    ---
    #title
    Multi-select

    #description
    Pick multiple values, show tags, remove with keyboard, and clear all at once.
    ::::

    ::::u-page-card
    ---
    spotlight: true
    class: col-span-2 lg:col-span-1
    icon: i-lucide-palette
    to: https://vue3-select-component.vercel.app/guide/styling
    ---
    #title
    Styling

    #description
    Style every part with stable data-attribute hooks and your own CSS.
    ::::
  :::
::