vootstrap-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 vootstrap-select

Peer dependencies:

• vue ^3.5.0
• bootstrap >=5.0.0

Usage

<script setup lang="ts">
import { ref } from "vue";
import { BootstrapSelect, type BootstrapSelectOptionInput } from "vootstrap-select";
import "vootstrap-select/styles";

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

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

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | options | BootstrapSelectOptionInput[] | [] | Option data | | modelValue | string \| string[] | — | v-model value | | multiple | boolean | false | Enable multiple selection | | disabled | boolean | false | Disable the select | | size | 'sm' \| 'md' \| 'lg' | 'md' | Button size | | menuSize | 'auto' \| number \| false | 'auto' | Number of visible items in menu | | placeholder | string \| null | null | Placeholder text | | liveSearch | boolean | false | Enable search/filter | | liveSearchPlaceholder | string \| null | null | Search input placeholder | | liveSearchStyle | 'contains' \| 'startsWith' | 'contains' | Search matching style | | liveSearchNormalize | boolean | false | Accent-insensitive search | | style | string | 'btn-light' | Button style class | | styleBase | string | 'btn' | Base button class | | width | 'auto' \| 'fit' \| string \| false | false | Select width | | maxOptions | number \| false | false | Max selections in multi-select | | actionsBox | boolean | false | Show select/deselect all buttons | | doneButton | boolean | false | Show done button | | doneButtonText | string | 'Close' | Done button text | | allowClear | boolean | false | Show clear button | | selectedTextFormat | string | 'values' | Display format: 'values', 'static', 'count' | | countSelectedText | function | — | Format function for count display | | multipleSeparator | string | ', ' | Separator for selected items | | selectAllText | string | 'Select All' | Select all button text | | deselectAllText | string | 'Deselect All' | Deselect all button text | | noneSelectedText | string | 'Nothing selected' | Text when nothing selected | | noneResultsText | string | 'No results matched {0}' | Text when no search results | | showSubtext | boolean | false | Show subtext in button | | showIcon | boolean | true | Show icons in button | | showContent | boolean | true | Show custom HTML content | | showTick | boolean | false | Checkmark on single-select | | iconBase | string | '' | Icon font base class (e.g. 'fa') | | tickIcon | string | 'bs-ok-default' | Checkmark icon class | | header | string \| false | false | Menu header text | | dropupAuto | boolean | true | Auto-detect dropup direction | | dropdownAlignRight | boolean \| 'auto' | false | Right-align dropdown | | container | string \| false | false | Append menu to container | | hideDisabled | boolean | false | Hide disabled options | | selectOnTab | boolean | true | Tab selects in dropdown | | virtualScroll | number \| boolean | 600 | Virtual scroll threshold | | sanitize | boolean | true | Enable HTML sanitization | | whiteList | object | — | Allowed HTML tags/attributes | | sanitizeFn | function \| null | null | Custom sanitize function | | source | object | — | Data source config (fetching/pagination) | | chunkSize | number | 40 | Options per virtual scroll chunk | | maxOptionsText | function \| string[] | — | Text when max selections reached | | mobile | boolean | false | Native mobile menu | | windowPadding | number \| number[] | 0 | Window padding for auto-size | | display | string \| false | false | Display style for dropdown | | template | object | — | Template overrides |

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?: BootstrapSelectOptionInput[]
  options?: BootstrapSelectOptionInput[] // alias for children
}

Events

| Event | Payload | Description | |-------|---------|-------------| | loaded | — | Fires after initialization | | rendered | — | Fires after button text is re-rendered | | refreshed | — | Fires after refresh() | | changed | ChangedArguments | Fires after value changes | | fetched | — | Fires after data is fetched | | show | Event | Fires when dropdown is shown | | shown | Event | Fires after dropdown is shown | | hide | Event | Fires when dropdown is hidden | | hidden | Event | Fires after dropdown is hidden | | maxReached | — | Fires when max options is reached | | maxReachedGrp | — | Fires when optgroup max is reached | | update:modelValue | value | v-model update |

Methods

Access via template ref:

picker.value?.val(value?)     // Get or set selected values
picker.value?.selectAll()     // Select all in multi-select
picker.value?.deselectAll()   // Deselect all in multi-select
picker.value?.refresh()       // Refresh UI after DOM changes
picker.value?.show()          // Show the select
picker.value?.hide()          // Hide the select

Styles

import "vootstrap-select/styles";

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