voo-select

voo-select

Vue 3 port of bootstrap-select with zero jQuery.

Disclaimer: This is a personal exploration project. I am not responsible for any malfunction or issues that may arise from its use.

Installation

pnpm add voo-select

Peer dependencies:

• vue ^3.5.0
• bootstrap >=5.0.0

Usage

<script setup lang="ts">
import { ref } from "vue";
import { VooSelect, type VooSelectOptionInput } from "voo-select";
import "voo-select/dist/voo-select.css";

const value = ref<string | string[]>();
const options: VooSelectOptionInput[] = [
  "Apple",
  { text: "Banana", value: "banana" },
  { text: "Cherry", value: "cherry", selected: true },
];
</script>

<template>
  <voo-select
    v-model="value"
    :options="options"
    placeholder="Pick one"
  />
</template>

Props

Text props (noneSelectedText, selectAllText, …) default to the active locale; passing one overrides the locale text.

options format

Accepts plain strings, option objects, or group (optgroup) objects:

// Simple string
"Apple"

// Option object
{
  text?: string
  value?: string | number
  html?: string
  selected?: boolean
  disabled?: boolean
  title?: string
  icon?: string
  subtext?: string
  tokens?: string
  className?: string
  style?: string
  divider?: boolean
}

// Optgroup
{
  label: string
  disabled?: boolean
  className?: string
  children?: VooSelectOptionInput[]
  options?: VooSelectOptionInput[] // alias for children
}

Slots

Use scoped slots to render Vue components instead of HTML strings. Each slot is optional; omitted slots use the existing HTML/text rendering.

<template lang="pug">
voo-select(v-model="value" :options="options")
  template(#option="{ option, selected, active, disabled }")
    my-option(:label="option.text" :selected="selected" :active="active" :disabled="disabled")
  template(#selected-option="{ option }")
    span.badge.text-bg-primary {{ option.text }}
  template(#optgroup="{ group }")
    strong {{ group.display }}
</template>

option and group are normalized OptionData records; group.display contains the sanitized group label. Treat slot props as read-only. Menu indexes include group headers/dividers and refer to the filtered list; selected-option indexes refer to the options displayed in the button. The exported VooSelectSlots, OptionSlotProps, SelectedOptionSlotProps and OptgroupSlotProps types describe these contracts.

Slots take precedence over HTML/text and the showIcon, showContent and showSubtext display flags. The button still respects placeholder, static/count formatting, separators and the 50-option display limit. The select keeps the option container, selection tick, keyboard navigation and ARIA state; use presentational content inside options rather than nested buttons, links or inputs.

Keep supplying text, value and optional tokens: search, keyboard typeahead, the button tooltip and native form submission use option data, not the rendered slot content. Vue slot content is rendered normally; the HTML sanitizer still applies to HTML strings, not to your Vue components or any v-html you add yourself.

Virtual lists mount slot components only for the rendered rows and measure their actual heights, including reactive size changes. Offscreen components can unmount; keep persistent state in the parent, keyed by option value.

Forms

With name or required, a hidden native <select> carries the value into <form> submissions (FormData) and native validation (checkValidity()). Only the selected options are mirrored into it, so large lists don't double the DOM size. Without name or required it isn't rendered.

Methods

Exposed through a template ref:

<script setup>
import { ref } from "vue";
const picker = ref();
picker.value?.val(["a", "b"]);
</script>

<template>
  <voo-select
    ref="picker"
    multiple
  />
</template>

Events

Styles

import "voo-select/dist/voo-select.css";

Bootstrap CSS must be loaded separately (either via CDN or your own import).

Development

pnpm install
pnpm dev        # Demo page with HMR
pnpm typecheck  # TypeScript check
pnpm build      # Typecheck + build library
pnpm test       # Run tests

The main demo includes a Vue slots playground section (/#slots) with reactive Vue components, multiple selection, Teleport, forms, HTML fallbacks and 10,000 virtual options.