Form Select ​

Overview ​

Generate your select options by passing an array or object to the options props:

<template>
  <BFormSelect
    v-model="selected"
    :options="ex1Options"
  />

  <BFormSelect
    v-model="selected"
    :options="ex1Options"
    size="sm"
    class="mt-3"
  />

  <div class="mt-3">
    Selected: <strong>{{ selected }}</strong>
  </div>
</template>

<script setup lang="ts">
import {ref} from 'vue'

const ex1Options = [
  {value: null, text: 'Please select an option'},
  {value: 'a', text: 'This is First option'},
  {value: 'b', text: 'Selected Option'},
  {value: {C: '3PO'}, text: 'This is an option with object value'},
  {value: 'd', text: 'This one is disabled', disabled: true},
]

const selected = ref(null)
</script>

You can even define option groups with the options prop:

<template>
  <BFormSelect
    v-model="selected"
    :options="ex1GroupOptions"
  />

  <div class="mt-3">
    Selected: <strong>{{ selected }}</strong>
  </div>
</template>

<script setup lang="ts">
import {ref} from 'vue'

const ex1GroupOptions = [
  {value: null, text: 'Please select an option'},
  {value: 'a', text: 'This is First option'},
  {value: 'b', text: 'Selected Option', disabled: true},
  {
    label: 'Grouped options',
    options: [
      {value: {C: '3PO'}, text: 'Option with object value'},
      {value: {R: '2D2'}, text: 'Another option with object value'},
    ],
  },
]

const selected = ref()
</script>

Or manually provide your options and option groups:

<template>
  <BFormSelect v-model="selected">
    <BFormSelectOption :value="null">Please select an option</BFormSelectOption>
    <BFormSelectOption value="a">Option A</BFormSelectOption>
    <BFormSelectOption
      value="b"
      disabled
      >Option B (disabled)</BFormSelectOption
    >
    <BFormSelectOptionGroup label="Grouped options">
      <BFormSelectOption :value="{C: '3PO'}">Option with object value</BFormSelectOption>
      <BFormSelectOption :value="{R: '2D2'}">Another option with object value</BFormSelectOption>
    </BFormSelectOptionGroup>
  </BFormSelect>

  <div class="mt-3">
    Selected: <strong>{{ selected }}</strong>
  </div>
</template>

<script setup lang="ts">
import {ref} from 'vue'

const selected = ref(null)
</script>

Feel free to mix the options prop with BFormSelectOption and BFormSelectOptionGroup. Manually placed options and option groups will appear below the options generated via the options prop. To place manual options and option groups above the options specified by the options prop, use the named slot first.

<template>
  <BFormSelect
    v-model="selected"
    :options="exFirstSlotOptions"
    class="mb-3"
  >
    <!-- This slot appears above the options from 'options' prop -->
    <template #first>
      <BFormSelectOption
        :value="undefined"
        disabled
        >-- Please select an option --</BFormSelectOption
      >
    </template>

    <!-- These options will appear after the ones from 'options' prop -->
    <BFormSelectOption value="C">Option C</BFormSelectOption>
    <BFormSelectOption value="D">Option D</BFormSelectOption>
  </BFormSelect>

  <div class="mt-3">
    Selected: <strong>{{ selected }}</strong>
  </div>
</template>

<script setup lang="ts">
import {ref} from 'vue'

const exFirstSlotOptions = [
  {value: 'A', text: 'Option A (from options prop)'},
  {value: 'B', text: 'Option B (from options prop)'},
]

const selected = ref<'A' | 'B' | 'C' | 'D' | undefined>()
</script>

Options property ​

options can be an array of strings or objects, or a key-value object. Available fields:

• value The selected value which will be set on v-model
• disabled Disables item for selection
• text Display text

value can be a string, number, or simple object. Avoid using complex types in values.

Options as an array ​

const options = ['A', 'B', 'C', {text: 'D', value: {d: 1}, disabled: true}, 'E', 'F']

If an array entry is a string, it will be used for both the generated value and text fields.

You can mix using strings and objects in the array.

Internally, BootstrapVueNext will convert the above array to the following array (the array of objects) format:

const options = [
  {text: 'A', value: 'A', disabled: false},
  {text: 'B', value: 'B', disabled: false},
  {text: 'C', value: 'C', disabled: false},
  {text: 'D', value: {d: 1}, disabled: true},
  {text: 'E', value: 'E', disabled: false},
  {text: 'F', value: 'F', disabled: false},
]

Options as an array of objects ​

const options = [
  {text: 'Item 1', value: 'first'},
  {text: 'Item 2', value: 'second'},
  {text: 'Item 3', value: 'third', disabled: true},
  {text: 'Item 4'},
  {text: 'Item 5', value: {foo: 'bar', baz: true}},
]

If value is missing, then text will be used as both the value and text fields.

Internally, BootstrapVueNext will convert the above array to the following array (the array of objects) format:

const options = [
  {text: 'Item 1', value: 'first', disabled: false},
  {text: 'Item 2', value: 'second', disabled: false},
  {text: 'Item 3', value: 'third', disabled: true},
  {text: 'Item 4', value: 'Item 4', disabled: false},
  {text: 'Item 5', value: 'E', disabled: false},
]

Changing the option field names ​

If you want to customize the field property names (for example using name field for display text) you can easily change them by setting the text-field, value-field, and disabled-field props to a string that contains the property name you would like to use:

<template>
  <BFormSelect
    v-model="selected"
    :options="exFieldNamesOptions"
    class="mb-3"
    value-field="item"
    text-field="name"
    disabled-field="notEnabled"
  />

  <div class="mt-3">
    Selected: <strong>{{ selected }}</strong>
  </div>
</template>

<script setup lang="ts">
import {ref} from 'vue'

const exFieldNamesOptions = [
  {item: 'A', name: 'Option A'},
  {item: 'B', name: 'Option B'},
  {item: 'D', name: 'Option C', notEnabled: true},
  {item: {d: 1}, name: 'Option D'},
]

const selected = ref('A')
</script>

Options groups ​

To define option groups, just add an object with a label prop as the groups name and a options property with the array of options of the group.

const options = [
  {text: 'Item 1', value: 'first'},
  {text: 'Item 2', value: 'second'},
  {
    label: 'Grouped options',
    options: [{text: 'Item< 3', value: 'third', disabled: true}, {text: 'Item 4'}],
  },
  {text: 'Item 5', value: {foo: 'bar', baz: true}},
]

Option notes ​

If the initial value of your v-model expression does not match any of the options, the BFormSelect component (which is a native HTML5 <select> under the hood) will render in an unselected state. On iOS this will cause the user not being able to select the first item because iOS does not fire a change event in this case. It is therefore recommended providing a disabled option with an empty value as your first option.

<BFormSelect
  v-model="selected"
  :options="options"
>
  <template #first>
    <BFormSelectOption
      value=""
      disabled
      >-- Please select an option --</BFormSelectOption
    >
  </template>
</BFormSelect>

See the Vue select documentation for more details.

Standard (single) select ​

By default, Bootstrap v5's custom select styling is applied.

Value in single mode ​

In non multiple mode, BFormSelect returns the single value of the currently selected option.

<template>
  <BFormSelect
    v-model="selected"
    :options="ex1Options"
  />

  <div class="mt-3">
    Selected: <strong>{{ selected }}</strong>
  </div>
</template>

<script setup lang="ts">
import {ref} from 'vue'

const ex1Options = [
  {value: null, text: 'Please select an option'},
  {value: 'a', text: 'This is First option'},
  {value: 'b', text: 'Selected Option'},
  {value: {C: '3PO'}, text: 'This is an option with object value'},
  {value: 'd', text: 'This one is disabled', disabled: true},
]

const selected = ref()
</script>

Select sizing (displayed rows) ​

You can use the select-size prop to switch the custom select into a select list-box, rather than a dropdown. Set the select-size prop to a numerical value greater than 1 to control how many rows of options are visible.

Note when select-size is set to a value greater than 1, the Bootstrap v5 custom styling will not be applied, unless the multiple prop is also set.

Note that not all mobile browsers will show the select as a list-box.

<template>
  <BFormSelect
    v-model="selected"
    :options="ex1Options"
    :select-size="4"
  />

  <div class="mt-3">
    Selected: <strong>{{ selected }}</strong>
  </div>
</template>

<script setup lang="ts">
import {ref} from 'vue'

const ex1Options = [
  {value: null, text: 'Please select an option'},
  {value: 'a', text: 'This is First option'},
  {value: 'b', text: 'Selected Option'},
  {value: {C: '3PO'}, text: 'This is an option with object value'},
  {value: 'd', text: 'This one is disabled', disabled: true},
]

const selected = ref()
</script>

Multiple select support ​

Enable multiple select mode by setting the prop multiple, and control how many rows are displayed in the multiple select list-box by setting select-size to the number of rows to display. The default is to let the browser use its default (typically 4).

Value in multiple mode ​

In multiple mode, BFormSelect always returns an array of option values. You must provide an array reference as your v-model when in multiple mode.

<template>
  <BFormSelect
    v-model="selected"
    :options="exMultiOptions"
    multiple
    :select-size="4"
  />

  <div class="mt-3">
    Selected: <strong>{{ selected }}</strong>
  </div>
</template>

<script setup lang="ts">
import {ref} from 'vue'

const exMultiOptions = [
  {value: 'a', text: 'This is First option'},
  {value: 'b', text: 'Default Selected Option'},
  {value: 'c', text: 'This is another option'},
  {value: 'd', text: 'This one is disabled', disabled: true},
  {value: 'e', text: 'This is option e'},
  {value: 'f', text: 'This is option f'},
  {value: 'g', text: 'This is option g'},
]

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

Control sizing ​

Set the form-control text size using the size prop to sm or lg for small or large respectively.

By default, BFormSelect will occupy the full width of the container that it appears in. To control the select width, place the input inside standard Bootstrap grid column.

Autofocus ​

When the autofocus prop is set on BFormSelect, the select will be auto-focused when it is inserted (i.e. mounted) into the document or re-activated when inside a Vue KeepAlive component. Note that this prop does not set the autofocus attribute on the select, nor can it tell when the select becomes visible.

TypeScript Type Safety ​

BFormSelect provides full TypeScript type safety through generic type parameters. When you provide typed options, TypeScript will:

1. Validate field names - Ensure value-field, text-field, and disabled-field props reference actual keys of your option type
2. Infer v-model type - Automatically determine the correct type for v-model based on your value-field

Basic Type-Safe Usage ​

<template>
  <BFormSelect
    v-model="selectedUserId"
    :options="users"
    value-field="id"
    text-field="name"
  />
  <p class="mt-2">Selected User ID: {{ selectedUserId }}</p>
</template>

<script setup lang="ts">
import {ref} from 'vue'

interface User {
  id: number
  name: string
  email: string
}

const users: User[] = [
  {id: 1, name: 'Alice', email: 'alice@example.com'},
  {id: 2, name: 'Bob', email: 'bob@example.com'},
  {id: 3, name: 'Charlie', email: 'charlie@example.com'},
]

// TypeScript infers that selectedUserId is of type: number
const selectedUserId = ref<number>()
</script>

In this example, TypeScript knows that selectedUserId is a number because the id field of User is typed as number.

Type-Safe Field Validation ​

TypeScript will catch errors when you use invalid field names:

<template>
  <!-- ✅ VALID: All fields exist on Product -->
  <BFormSelect
    id="select-type-safe-validation"
    v-model="selectedProduct"
    :options="products"
    value-field="productId"
    text-field="productName"
  />

  <!-- ❌ This would cause TypeScript errors (uncomment to test):
  <BFormSelect
    v-model="selectedProduct"
    :options="products"
    value-field="id"
    text-field="productName"
  />
  Error: Type '"id"' is not assignable to type 'keyof Product'
  -->

  <p class="mt-2">Selected Product ID: {{ selectedProduct }}</p>
</template>

<script setup lang="ts">
import {ref} from 'vue'

interface Product {
  productId: number
  productName: string
  price: number
}

const products: Product[] = [
  {productId: 1, productName: 'Widget', price: 19.99},
  {productId: 2, productName: 'Gadget', price: 29.99},
]

const selectedProduct = ref<number>()
</script>

Multiple Select with Type Safety ​

Type safety works seamlessly with multiple select mode:

<template>
  <BFormSelect
    v-model="selectedTags"
    :options="tags"
    value-field="tagId"
    text-field="tagName"
    multiple
  />
  <p class="mt-2">Selected Tags: {{ selectedTags.join(', ') || 'None' }}</p>
</template>

<script setup lang="ts">
import {ref} from 'vue'

interface Tag {
  tagId: string
  tagName: string
}

const tags: Tag[] = [
  {tagId: 'vue', tagName: 'Vue.js'},
  {tagId: 'ts', tagName: 'TypeScript'},
  {tagId: 'bs', tagName: 'Bootstrap'},
]

// TypeScript knows this is readonly string[]
const selectedTags = ref<readonly string[]>([])
</script>

Type-Safe API Responses ​

Type safety is especially valuable when working with API data that uses different naming conventions:

<template>
  <BFormSelect
    v-model="selectedUserId"
    :options="users"
    value-field="user_id"
    text-field="user_name"
  />
  <p class="mt-2">Selected User ID: {{ selectedUserId }}</p>
  <p class="text-muted small">TypeScript validates snake_case field names from API</p>
</template>

<script setup lang="ts">
import {ref} from 'vue'

interface ApiUser {
  user_id: number // API uses snake_case
  user_name: string
  user_email: string
  is_active: boolean
}

// In a real app, you'd fetch from API:
// onMounted(async () => {
//   const response = await fetch('/api/users')
//   users.value = await response.json()
// })

const users: ApiUser[] = [
  {user_id: 1, user_name: 'Alice', user_email: 'alice@example.com', is_active: true},
  {user_id: 2, user_name: 'Bob', user_email: 'bob@example.com', is_active: false},
]

const selectedUserId = ref<ApiUser['user_id'] | undefined>(undefined)
</script>

Type-Safe Enums ​

Type safety works with TypeScript enums for strongly-typed value constraints:

export enum Status {
  Active = 'ACTIVE',
  Inactive = 'INACTIVE',
  Pending = 'PENDING',
}

export interface StatusOption {
  value: Status
  text: string
}

export const statusOptions: StatusOption[] = [
  {value: Status.Active, text: 'Active'},
  {value: Status.Inactive, text: 'Inactive'},
  {value: Status.Pending, text: 'Pending'},
]

<template>
  <BFormSelect
    v-model="currentStatus"
    :options="statusOptions"
  />
  <p class="mt-2">Selected Status: {{ currentStatus }}</p>
</template>

<script setup lang="ts">
import {ref} from 'vue'
import {Status, statusOptions} from './SelectTypeSafeEnumTypes'

// TypeScript knows this is of type Status
const currentStatus = ref<Status>(statusOptions[0].value)
</script>

Benefits ​

• IDE autocomplete - Your editor suggests valid field names as you type
• Compile-time validation - Typos and invalid field names are caught before runtime
• Type inference - The v-model type is automatically inferred from your value field
• Refactoring safety - Renaming fields in your interface updates all usages

Backward Compatibility ​

Type safety is completely opt-in and maintains 100% backward compatibility. Existing code without explicit types continues to work exactly as before:

<!-- Works without type annotations -->
<ComponentName v-model="selected" :options="items" />

To enable type safety, simply provide explicit types for your data:

interface MyItem {
  id: number
  name: string
}

const items: MyItem[] = [...]

Global Defaults Limitation ​

Due to technical limitations with TypeScript generic components, this component cannot fully participate in the global defaults system provided by createBootstrap({ components: {...} }) or BApp. However:

• ✅ Commonly-customized props like buttonVariant, size, and state DO support global defaults
• ⚠️ Other props will use their hardcoded default values only
• ✅ You can still override any prop on individual component instances

This trade-off enables full type safety with IDE autocomplete and compile-time validation.

Props That Support Global Defaults ​

The following props support both component-specific defaults and global defaults:

• button-variant - Button variant for button-style checkboxes/radios (default: 'secondary')
• size - Size of the checkbox/radio (default: 'md')
• state - Validation state (default: null)

Default Value Precedence ​

When using these components, default values are resolved in this order (highest priority first):

1. Explicit prop on component instance - Value you provide directly
2. Component-specific defaults - Set via <BApp :defaults="{ BFormCheckboxGroup: {...} }"> or createBootstrap({ components: { BFormCheckboxGroup: {...} } })
3. Global defaults - Set via <BApp :defaults="{ global: {...} }"> or createBootstrap({ components: { global: {...} } })
4. Hardcoded default - Component's built-in fallback value

Example:

BApp Pattern:

<template>
  <BApp
    :defaults="{
      global: {
        buttonVariant: 'primary', // Applied to all components
        size: 'lg',
      },
      BFormCheckboxGroup: {
        buttonVariant: 'danger', // Specific to checkbox groups
        size: 'sm',
      },
    }"
  >
    <!-- Uses component defaults: danger variant, sm size -->
    <BFormCheckboxGroup
      :options="options"
      buttons
    />

    <!-- Explicit prop overrides everything: success variant -->
    <BFormCheckboxGroup
      :options="options"
      buttons
      button-variant="success"
    />

    <!-- Individual checkboxes outside a group use global defaults: primary variant -->
    <BFormCheckbox
      button
      value="a"
      >Option A</BFormCheckbox
    >
  </BApp>
</template>

<script setup lang="ts">
const options = [
  {text: 'Option 1', value: 1},
  {text: 'Option 2', value: 2},
]
</script>

Plugin Pattern:

// In main.ts or app setup:
import {createBootstrap} from 'bootstrap-vue-next'

app.use(
  createBootstrap({
    components: {
      global: {
        buttonVariant: 'primary', // Applied to all components
        size: 'lg',
      },
      BFormCheckboxGroup: {
        buttonVariant: 'danger', // Specific to checkbox groups
        size: 'sm',
      },
    },
  })
)

// This WILL work for size and state:
createBootstrap({
  components: {
    BFormSelect: {
      size: 'lg', // ✅ Will be applied
      state: false, // ✅ Will be applied
      multiple: false, // ⚠️ Will NOT be applied (use prop override)
    },
    global: {
      size: 'sm', // ✅ Will be applied as fallback if BFormSelect.size not set
    },
  },
})

Contextual states ​

Bootstrap includes validation styles for valid and invalid states on most form controls.

Generally speaking, you'll want to use a particular state for specific types of feedback:

• false (denotes invalid state) is great for when there is a blocking or required field. A user must fill in this field properly to submit the form
• true (denotes valid state) is ideal for situations when you have per-field validation throughout a form and want to encourage a user through the rest of the fields
• null Displays no validation state (neither valid nor invalid)

To apply one of the contextual state icons on BFormSelect, set the state prop to false (for invalid), true (for valid), or null (no validation state).

Conveying contextual validation state to assistive technologies and colorblind users ​

Using these contextual states to denote the state of a form control only provides a visual, color-based indication, which will not be conveyed to users of assistive technologies - such as screen readers - or to colorblind users.

Ensure that an alternative indication of state is also provided. For instance, you could include a hint about state in the form control's <label> text itself, or by providing an additional help text block (via BFormGroup or BForm*Feedback). Specifically for assistive technologies, invalid form controls can also be assigned an aria-invalid="true" attribute (see below).

ARIA aria-invalid attribute ​

When BFormSelect has an invalid contextual state (i.e. state = false) you may also want to set the BFormSelect prop aria-invalid to true.

Supported invalid values are:

• false (default) No errors detected
• true The value has failed validation

When state is set to false, aria-invalid will also be set to true.

Non custom style select ​

Set the prop plain to have a native browser <select> rendered (although the class .form-control will always be placed on the select).

A plain select will always be rendered for non multiple selects which have the select-size prop set to a value greater than 1.