Form Select

Bootstrap custom <select> using custom styles. Optionally specify options based on an array, array of objects, or an object.

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

<template>
  <div>
    <b-form-select v-model="selected" :options="options"></b-form-select>
    <b-form-select v-model="selected" :options="options" size="sm" class="mt-3"></b-form-select>
    <div class="mt-3">Selected: <strong>{{ selected }}</strong></div>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        selected: null,
        options: [
          { 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 }
        ]
      }
    }
  }
</script>

<!-- b-form-select-options.vue -->

You can even define option groups with the options prop:

<template>
  <div>
    <b-form-select v-model="selected" :options="options"></b-form-select>
    <div class="mt-3">Selected: <strong>{{ selected }}</strong></div>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        selected: null,
        options: [
          { 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' }
            ]
          }
        ]
      }
    }
  }
</script>

<!-- b-form-select-options.vue -->

Or manually provide your options and option groups:

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

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

<script>
  export default {
    data() {
      return {
        selected: null
      }
    }
  }
</script>

<!-- b-form-select-manual.vue -->

Feel free to mix the options prop with <b-form-select-option> and <b-form-select-option-group>. 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>
  <div>
    <b-form-select v-model="selected" :options="options" class="mb-3">
      <!-- This slot appears above the options from 'options' prop -->
      <template #first>
        <b-form-select-option :value="null" disabled>-- Please select an option --</b-form-select-option>
      </template>

      <!-- These options will appear after the ones from 'options' prop -->
      <b-form-select-option value="C">Option C</b-form-select-option>
      <b-form-select-option value="D">Option D</b-form-select-option>
    </b-form-select>

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

<script>
  export default {
    data() {
      return {
        selected: null,
        options: [
          { value: 'A', text: 'Option A (from options prop)' },
          { value: 'B', text: 'Option B (from options prop)' }
        ]
      }
    }
  }
</script>

<!-- b-form-select-both.vue -->

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, or html Display basic inline html

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

If both html and text are provided, html will take precedence. Only basic/native HTML is supported in the html field (components will not work). Note that not all browsers will render inline html (i.e. <i>, <strong>, etc.) inside <option> elements of a <select>.

Be cautious of placing user supplied content in the html field, as it may make you vulnerable to XSS attacks, if you do not first sanitize the user supplied string.

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, BootstrapVue 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' },
  { html: '<b>Item</b> 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. If you use the html property, you must supply a value property.

New in v2.2.0 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: [{ html: '<b>Item</b> 3', value: 'third', disabled: true }, { text: 'Item 4' }]
  },
  { text: 'Item 5', value: { foo: 'bar', baz: true } }
]

Options as an object

Deprecated

Keys are mapped to value and values are mapped to option text.

const options = {
  a: 'Item A',
  b: 'Item B',
  c: { html: 'Item C', disabled: true },
  d: { text: 'Item D', value: 'overridden_value' },
  e: { text: 'Item E', value: { foo: 'bar', baz: true } }
}

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

const options = [
  { text: 'Item A', value: 'a', disabled: false },
  { text: 'Item B', value: 'b', disabled: false },
  { html: 'Item C', value: 'c', disabled: false },
  { text: 'Item D', value: 'overridden_value', disabled: true },
  { text: 'Item E', value: { foo: 'bar', baz: true }, disabled: false }
]

Note: When using the Object format, the order of the final array is not guaranteed. For this reason, it is recommended to use either of the previously mentioned array formats.

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, html-field, value-field, and disabled-field props to a string that contains the property name you would like to use:

<template>
  <div>
    <b-form-select
      v-model="selected"
      :options="options"
      class="mb-3"
      value-field="item"
      text-field="name"
      disabled-field="notEnabled"
    ></b-form-select>

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

<script>
  export default {
    data() {
      return {
        selected: 'A',
        options: [
          { item: 'A', name: 'Option A' },
          { item: 'B', name: 'Option B' },
          { item: 'D', name: 'Option C', notEnabled: true },
          { item: { d: 1 }, name: 'Option D' }
        ]
      }
    }
  }
</script>

<!-- b-form-select-options-fields.vue -->

Option notes

If the initial value of your v-model expression does not match any of the options, the <b-form-select> 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 to provide a disabled option with an empty value as your first option.

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

See the Vue select documentation for more details.

Standard (single) select

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

Value in single mode

In non multiple mode, <b-form-select> returns the a single value of the currently selected option.

<template>
  <div>
    <b-form-select v-model="selected" :options="options"></b-form-select>
    <div class="mt-3">Selected: <strong>{{ selected }}</strong></div>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        selected: null,
        options: [
          { value: null, text: 'Please select some item' },
          { 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 }
        ]
      }
    }
  }
</script>

<!-- b-form-select-single.vue -->

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 v4 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>
  <div>
    <b-form-select v-model="selected" :options="options" :select-size="4"></b-form-select>
    <div class="mt-3">Selected: <strong>{{ selected }}</strong></div>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        selected: null,
        options: [
          { value: null, text: 'Please select some item' },
          { value: 'a', text: 'This is option a' },
          { value: 'b', text: 'Default Selected Option b' },
          { value: 'c', text: 'This is option c' },
          { value: 'd', text: 'This one is disabled', disabled: true },
          { value: 'e', text: 'This is option e' },
          { value: 'e', text: 'This is option f' }
        ]
      }
    }
  }
</script>

<!-- b-form-select-size.vue -->

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, <b-form-select> always returns an array of option values. You must provide an array reference as your v-model when in multiple mode.

<template>
  <div>
    <b-form-select v-model="selected" :options="options" multiple :select-size="4"></b-form-select>
    <div class="mt-3">Selected: <strong>{{ selected }}</strong></div>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        selected: ['b'], // Array reference
        options: [
          { 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' }
        ]
      }
    }
  }
</script>

<!-- b-form-select-multiple-mode.vue -->

Control sizing

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

By default <b-form-select> 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 <b-form-select>, the select will be auto-focused when it is inserted (i.e. mounted) into the document or re-activated when inside a Vue <keep-alive> component. Note that this prop does not set the autofocus attribute on the select, nor can it tell when the select becomes visible.

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's 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 <b-form-select>, 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 <b-form-group> or <b-form-*-feedback>). Specifically for assistive technologies, invalid form controls can also be assigned an aria-invalid="true" attribute (see below).

ARIA `aria-invalid` attribute:

When <b-form-select> has an invalid contextual state (i.e. state = false) you may also want to set the <b-form-select> 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 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.

Component reference

`<b-form-select>`

View source

<b-form-select> Component aliases
<b-form-select> Properties
<b-form-select> v-model
<b-form-select> Slots
<b-form-select> Events

Component aliases

<b-form-select> can also be used via the following aliases:

<b-select>

Note: component aliases are only available when importing all of BootstrapVue or using the component group plugin.

Properties

All property default values are globally configurable.

Property (Click to sort Ascending)	Type (Click to sort Ascending)	Default	Description
`aria-invalid`	`Boolean` or `String`	`false`	Optional value to set for the 'aria-invalid' attribute. Supported values are 'true' and 'false'. If not set, the 'state' prop will dictate the value
`autofocus`	`Boolean`	`false`	When set to `true`, attempts to auto-focus the control when it is mounted, or re-activated when in a keep-alive. Does not set the `autofocus` attribute on the control
`disabled`	`Boolean`	`false`	When set to `true`, disables the component's functionality and places it in a disabled state
`disabled-field`	`String`	`'disabled'`	Field name in the `options` array that should be used for the disabled state
`form`	`String`		ID of the form that the form control belongs to. Sets the `form` attribute on the control
`html-field` Use with caution	`String`	`'html'`	Field name in the `options` array that should be used for the html label instead of text field
`id`	`String`		Used to set the `id` attribute on the rendered content, and used as the base to generate any additional element IDs as needed
`label-field`	`String`	`'label'`	The key to use from the option object to get the label
`multiple`	`Boolean`	`false`	When set, allows multiple options to be selected (multi-select)
`name`	`String`		Sets the value of the `name` attribute on the form control
`options`	`Array` or `Object`	`[]`	Array of items to render in the component
`options-field`	`String`	`'options'`	The key to use from the option object to get the options
`plain`	`Boolean`	`false`	Render the form control in plain mode, rather than custom styled mode
`required`	`Boolean`	`false`	Adds the `required` attribute to the form control
`select-size`	`Number`	`0`	When set to a number larger than 0, will set the number of display option rows. Note not all browser will respect this setting
`size`	`String`		Set the size of the component's appearance. 'sm', 'md' (default), or 'lg'
`state`	`Boolean`	`null`	Controls the validation state appearance of the component. `true` for valid, `false` for invalid, or `null` for no validation state
`text-field`	`String`	`'text'`	Field name in the `options` array that should be used for the text label
`value` v-model	`Any`		Current value of the select. Should be set to an array when the 'multiple' prop is set
`value-field`	`String`	`'value'`	Field name in the `options` array that should be used for the value

Caution: Props that support HTML strings (*-html) can be vulnerable to Cross Site Scripting (XSS) attacks when passed raw user supplied values. You must properly sanitize the user input first!

`v-model`

Property	Event
`value`	`input`

Slots

Name	Description
`default`	Content to place in the form select
`first`	Slot to place options or option groups above options provided via the 'options' prop

Events

Event	Arguments	Description
`change`	`value` - Current selected value(s) of the select	Emitted when the select value changes via user interaction
`input`	`value` - Current selected value(s) of the select	Emitted when the select value changes

`<b-form-select-option>`

v2.2.0+ Functional component

View source

<b-form-select-option> Component aliases
<b-form-select-option> Properties
<b-form-select-option> Slots

Component aliases

<b-form-select-option> can also be used via the following aliases:

<b-select-option>

Note: component aliases are only available when importing all of BootstrapVue or using the component group plugin.

Properties

All property default values are globally configurable.

Property	Type	Default	Description
`disabled`	`Boolean`	`false`	When set to `true`, disables the component's functionality and places it in a disabled state
`value` Required	`Any`		The value of the option

Slots

Name	Description
`default`	Content to place in the form select option

`<b-form-select-option-group>`

v2.2.0+

View source

<b-form-select-option-group> Component aliases
<b-form-select-option-group> Properties
<b-form-select-option-group> Slots

Component aliases

<b-form-select-option-group> can also be used via the following aliases:

<b-select-option-group>

Note: component aliases are only available when importing all of BootstrapVue or using the component group plugin.

Properties

All property default values are globally configurable.

Property	Type	Default	Description
`disabled-field`	`String`	`'disabled'`	Field name in the `options` array that should be used for the disabled state
`html-field` Use with caution	`String`	`'html'`	Field name in the `options` array that should be used for the html label instead of text field
`label` Required	`String`		The label for the option group
`options`	`Array` or `Object`	`[]`	Array of items to render in the component
`text-field`	`String`	`'text'`	Field name in the `options` array that should be used for the text label
`value-field`	`String`	`'value'`	Field name in the `options` array that should be used for the value

Caution: Props that support HTML strings (*-html) can be vulnerable to Cross Site Scripting (XSS) attacks when passed raw user supplied values. You must properly sanitize the user input first!

Slots

Name	Description
`default`	Content to place in the form select option group
`first`	Slot to place options above options provided via the 'options' prop

Importing individual components

You can import individual components into your project via the following named exports:

Component	Named Export	Import Path
`<b-form-select>`	`BFormSelect`	`bootstrap-vue`
`<b-form-select-option>`	`BFormSelectOption`	`bootstrap-vue`
`<b-form-select-option-group>`	`BFormSelectOptionGroup`	`bootstrap-vue`

Example:

import { BFormSelect } from 'bootstrap-vue'
Vue.component('b-form-select', BFormSelect)

Importing as a Vue.js plugin

This plugin includes all of the above listed individual components. Plugins also include any component aliases.

Named Export	Import Path
`FormSelectPlugin`	`bootstrap-vue`

Example:

import { FormSelectPlugin } from 'bootstrap-vue'
Vue.use(FormSelectPlugin)

Options property

Options as an array

Options as an array of objects

Options as an object

Changing the option field names

Option notes

Standard (single) select

Value in single mode

Select sizing (displayed rows)

Multiple select support

Value in multiple mode

Control sizing

Autofocus

Contextual states

Conveying contextual validation state to assistive technologies and colorblind users

ARIA aria-invalid attribute:

Non custom select

Component reference

Component aliases

Properties

v-model

Slots

Events

Component aliases

Properties

Slots

Component aliases

Properties

Slots

Importing individual components

Importing as a Vue.js plugin

ARIA `aria-invalid` attribute:

`v-model`