Select

When there are plenty of options, use a drop-down menu to display and select desired ones.

Basic usage

v-model is the value of b-option that is currently selected.

---

<template>
  <b-space>
    <b-select v-model="value" placeholder="Select" large>
      <b-option
        v-for="item in options"
        :key="item.value"
        :label="item.label"
        :value="item.value"
      />
    </b-select>
    <b-select v-model="value" placeholder="Select">
      <b-option
        v-for="item in options"
        :key="item.value"
        :label="item.label"
        :value="item.value"
      />
    </b-select>
    <b-select v-model="value" placeholder="Select" small>
      <b-option
        v-for="item in options"
        :key="item.value"
        :label="item.label"
        :value="item.value"
      />
    </b-select>
  </b-space>
</template>

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

const value = ref('')

const options = [
  {
    value: 'Option1',
    label: 'Option1',
  },
  {
    value: 'Option2',
    label: 'Option2',
  },
  {
    value: 'Option3',
    label: 'Option3',
  },
  {
    value: 'Option4',
    label: 'Option4',
  },
  {
    value: 'Option5',
    label: 'Option5',
  },
]
</script>

Disabled option

Set the value of disabled in b-option to true to disable this option.

---

<template>
  <b-space>
    <b-select v-model="value" placeholder="Select" class="w-280px">
      <b-option
        v-for="item in options"
        :key="item.value"
        :label="item.label"
        :value="item.value"
        :disabled="item.disabled"
      />
    </b-select>
    <b-select v-model="value" placeholder="Select" disabled>
      <b-option
        v-for="item in options"
        :key="item.value"
        :label="item.label"
        :value="item.value"
        :disabled="item.disabled"
      />
    </b-select>
  </b-space>
</template>

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

const value = ref('')
const options = [
  {
    value: 'Option1',
    label: 'Option1',
  },
  {
    value: 'Option2',
    label: 'Option2',
    disabled: true,
  },
  {
    value: 'Option3',
    label: 'Option3',
  },
  {
    value: 'Option4',
    label: 'Option4',
  },
  {
    value: 'Option5',
    label: 'Option5',
  },
]
</script>

Clearable single select

You can clear Select using a clear icon.

Set clearable attribute for b-select and a clear icon will appear. Note that clearable is only for single select.

---

<template>
  <b-select v-model="value" clearable placeholder="Select" class="w-280px">
    <b-option
      v-for="item in options"
      :key="item.value"
      :label="item.label"
      :value="item.value"
    />
  </b-select>
</template>

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

const value = ref('')
const options = [
  {
    value: 'Option1',
    label: 'Option1',
  },
  {
    value: 'Option2',
    label: 'Option2',
  },
  {
    value: 'Option3',
    label: 'Option3',
  },
  {
    value: 'Option4',
    label: 'Option4',
  },
  {
    value: 'Option5',
    label: 'Option5',
  },
]
</script>

Multiple select

Multiple select uses tags to display selected options.

Set multiple attribute for b-select to enable multiple mode. In this case, the value of v-model will be an array of selected options. By default the selected options will be displayed as Tags. You can collapse them to a text by using collapse-tags attribute. You can check them when mouse hover collapse text by using collapse-tags-tooltip attribute.

---

<template>
  <b-row>
    <b-col>
      <b-select v-model="value1" multiple placeholder="Select">
        <b-option
          v-for="item in options"
          :key="item.value"
          :label="item.label"
          :value="item.value"
        />
      </b-select>
    </b-col>
    <b-col>
      <b-select v-model="value2" multiple collapse-tags placeholder="Select">
        <b-option
          v-for="item in options"
          :key="item.value"
          :label="item.label"
          :value="item.value"
        />
      </b-select>
    </b-col>
  </b-row>
</template>

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

const value1 = ref([])
const value2 = ref([])
const value3 = ref([])
const options = [
  {
    value: 'Option1',
    label: 'Option1',
  },
  {
    value: 'Option2',
    label: 'Option2',
  },
  {
    value: 'Option3',
    label: 'Option3',
  },
  {
    value: 'Option4',
    label: 'Option4',
  },
  {
    value: 'Option5',
    label: 'Option5',
  },
]
</script>

Custom template

You can customize HTML templates for options.

Insert customized HTML templates into the slot of b-option.

---

<template>
  <b-select v-model="value" placeholder="Select" class="w-280px">
    <b-option
      v-for="item in cities"
      :key="item.value"
      :label="item.label"
      :value="item.value"
      class="flex"
    >
      <span class="grow">{{ item.label }}</span>
      <span class="b-c-neutral-7">{{ item.value }}</span>
    </b-option>
  </b-select>
</template>

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

const value = ref('')
const cities = [
  {
    value: 'Beijing',
    label: 'Beijing',
  },
  {
    value: 'Shanghai',
    label: 'Shanghai',
  },
  {
    value: 'Nanjing',
    label: 'Nanjing',
  },
  {
    value: 'Chengdu',
    label: 'Chengdu',
  },
  {
    value: 'Shenzhen',
    label: 'Shenzhen',
  },
  {
    value: 'Guangzhou',
    label: 'Guangzhou',
  },
]
</script>

Grouping

Display options in groups.

Use b-option-group to group the options, and its label attribute stands for the name of the group.

---

<template>
  <b-select v-model="value" placeholder="Select" class="w-280px">
    <b-option-group
      v-for="group in options"
      :key="group.label"
      :label="group.label"
    >
      <b-option
        v-for="item in group.options"
        :key="item.value"
        :label="item.label"
        :value="item.value"
      />
    </b-option-group>
  </b-select>
</template>

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

const value = ref('')
const options = [
  {
    label: 'Popular cities',
    options: [
      {
        value: 'Ho Chi Minh City',
        label: 'Ho Chi Minh City',
      },
      {
        value: 'Ha Noi',
        label: 'Ha Noi',
      },
    ],
  },
  {
    label: 'Cities',
    options: [
      {
        value: 'Da Nang',
        label: 'Da Nang',
      },
      {
        value: 'Hai Phong',
        label: 'Hai Phong',
      },
      {
        value: 'Can Tho',
        label: 'Can Tho',
      },
      {
        value: 'Dong Nai',
        label: 'Dong Nai',
      },
    ],
  },
]
</script>

Option filtering

You can filter options for your desired ones.

Adding filterable to b-select enables filtering. By default, Select will find all the options whose label attribute contains the input value. If you prefer other filtering strategies, you can pass the filter-method. filter-method is a Function that gets called when the input value changes, and its parameter is the current input value.

---

<template>
  <b-select v-model="value" filterable placeholder="Select" class="w-280px">
    <b-option
      v-for="item in options"
      :key="item.value"
      :label="item.label"
      :value="item.value"
    />
  </b-select>
</template>

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

const value = ref('')
const options = [
  {
    value: 'Option1',
    label: 'Option1',
  },
  {
    value: 'Option2',
    label: 'Option2',
  },
  {
    value: 'Option3',
    label: 'Option3',
  },
  {
    value: 'Option4',
    label: 'Option4',
  },
  {
    value: 'Option5',
    label: 'Option5',
  },
]
</script>

Remote Search

Enter keywords and search data from server.

Set the value of filterable and remote with true to enable remote search, and you should pass the remote-method. remote-method is a Function that gets called when the input value changes, and its parameter is the current input value. Note that if b-option is rendered with the v-for directive, you should add the key attribute for b-option. Its value needs to be unique, such as item.value in the following example.

---

<template>
  <b-select
    v-model="value"
    multiple
    filterable
    remote
    reserve-keyword
    placeholder="Please enter a keyword"
    :remote-method="remoteMethod"
    :loading="loading"
    class="w-280px"
  >
    <b-option
      v-for="item in options"
      :key="item.value"
      :label="item.label"
      :value="item.value"
    />
  </b-select>
</template>

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

interface ListItem {
  value: string
  label: string
}

const list = ref<ListItem[]>([])
const options = ref<ListItem[]>([])
const value = ref<string[]>([])
const loading = ref(false)

onMounted(() => {
  list.value = states.map((item) => {
    return { value: `${item}`, label: `${item}` }
  })
})

const remoteMethod = (query: string) => {
  if (query) {
    loading.value = true
    setTimeout(() => {
      loading.value = false
      options.value = list.value.filter((item) => {
        return item.label.toLowerCase().includes(query.toLowerCase())
      })
    }, 200)
  } else {
    options.value = []
  }
}

const states = [
  'Alabama',
  'Alaska',
  'Arizona',
  'Arkansas',
  'California',
  'Colorado',
  'Connecticut',
  'Delaware',
  'Florida',
  'Georgia',
  'Hawaii',
  'Idaho',
  'Illinois',
  'Indiana',
  'Iowa',
  'Kansas',
  'Kentucky',
  'Louisiana',
  'Maine',
  'Maryland',
  'Massachusetts',
  'Michigan',
  'Minnesota',
  'Mississippi',
  'Missouri',
  'Montana',
  'Nebraska',
  'Nevada',
  'New Hampshire',
  'New Jersey',
  'New Mexico',
  'New York',
  'North Carolina',
  'North Dakota',
  'Ohio',
  'Oklahoma',
  'Oregon',
  'Pennsylvania',
  'Rhode Island',
  'South Carolina',
  'South Dakota',
  'Tennessee',
  'Texas',
  'Utah',
  'Vermont',
  'Virginia',
  'Washington',
  'West Virginia',
  'Wisconsin',
  'Wyoming',
]
</script>

Create new items

Create and select new items that are not included in select options

By using the allow-create attribute, users can create new items by typing in the input box. Note that for allow-create to work, filterable must be true. This example also demonstrates default-first-option. When this attribute is set to true, you can select the first option in the current option list by hitting enter without having to navigate with mouse or arrow keys.

---

<template>
  <b-select
    v-model="value"
    multiple
    filterable
    allow-create
    default-first-option
    :reserve-keyword="false"
    placeholder="Choose tags for your article"
  >
    <b-option
      v-for="item in options"
      :key="item.value"
      :label="item.label"
      :value="item.value"
    />
  </b-select>
</template>

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

const value = ref<string[]>([])
const options = [
  {
    value: 'HTML',
    label: 'HTML',
  },
  {
    value: 'CSS',
    label: 'CSS',
  },
  {
    value: 'JavaScript',
    label: 'JavaScript',
  },
]
</script>

TIP

If the binding value of Select is an object, make sure to assign value-key as its unique identity key name.

Select Attributes

Name	Description	Type	Accepted Values	Default
model-value / v-model	binding value	array / string / number / boolean / object	—	—
multiple	whether multiple-select is activated	boolean	true / false	false
disabled	whether Select is disabled	boolean	true / false	false
value-key	unique identity key name for value, required when value is an object	string	—	value
size	size of Input	string	large/default/small	default
clearable	whether select can be cleared	boolean	true / false	false
collapse-tags	whether to collapse tags to a text when multiple selecting	boolean	true / false	false
collapse-tags-tooltip	whether show all selected tags when mouse hover text of collapse-tags. To use this, collapse-tags must be true	boolean	true / false	false
multiple-limit	maximum number of options user can select when multiple is true. No limit when set to 0	number	—	0
name	the name attribute of select input	string	—	—
effect	Tooltip theme, built-in theme: dark / light	string	string	light
autocomplete	the autocomplete attribute of select input	string	—	off
placeholder	placeholder	string	—	Select
filterable	whether Select is filterable	boolean	true / false	false
allow-create	whether creating new items is allowed. To use this, filterable must be true	boolean	true / false	false
filter-method	custom filter method	function	—	—
remote	whether options are loaded from server	boolean	true / false	false
remote-method	custom remote search method	function	—	—
remote-show-suffix	in remote search method show suffix icon	boolean	true / false	false
loading	whether Select is loading data from server	boolean	true / false	false
loading-text	displayed text while loading data from server	string	—	Loading
no-match-text	displayed text when no data matches the filtering query, you can also use slot empty	string	—	No matching data
no-data-text	displayed text when there is no options, you can also use slot empty	string	—	No data
popper-class	custom class name for Select's dropdown	string	—	—
reserve-keyword	when multiple and filter is true, whether to reserve current keyword after selecting an option	boolean	true / false	true
default-first-option	select first matching option on enter key. Use with filterable or remote	boolean	true / false	false
popper-append-to-body(deprecated)	whether to append the popper menu to body. If the positioning of the popper is wrong, you can try to set this prop to false	boolean	true / false	true
teleported	whether select dropdown is teleported to the body	boolean	true / false	true
persistent	when select dropdown is inactive and persistent is false, select dropdown will be destroyed	boolean	true / false	true
automatic-dropdown	for non-filterable Select, this prop decides if the option menu pops up when the input is focused	boolean	true / false	false
clear-icon	Custom clear icon component	string | Component	—	Clear
fit-input-width	whether the width of the dropdown is the same as the input	boolean	true / false	false
suffix-icon	Custom suffix icon component	string | Component	—	ActionDown
suffix-transition	animation when dropdown appears/disappears icon	boolean	true / false	true
tag-type	tag type	string	success / info / warning / danger	info
validate-event	whether to trigger form validation	boolean	true / false	true
placement	position of dropdown	string	top / top-start / top-end / bottom / bottom-start / bottom-end / left / left-start / left-end / right / right-start / right-end	bottom
large	large input	boolean	—	false
small	small input	boolean	—	false

Select Events

Name	Description	Parameters
change	triggers when the selected value changes	current selected value
visible-change	triggers when the dropdown appears/disappears	true when it appears, and false otherwise
remove-tag	triggers when a tag is removed in multiple mode	removed tag value
clear	triggers when the clear icon is clicked in a clearable Select	—
blur	triggers when Input blurs	(event: FocusEvent)
focus	triggers when Input focuses	(event: FocusEvent)

Select Slots

Name	Description	Subtags
—	Option component list	Option Group / Option
prefix	content as Select prefix	—
empty	content when there is no options	—

Option Group Attributes

Name	Description	Type	Accepted Values	Default
label	name of the group	string	—	—
disabled	whether to disable all options in this group	boolean	—	false

Option Group Slots

Name	Description	Subtags
-	customize default content	Option

Option Attributes

Name	Description	Type	Accepted Values	Default
value	value of option	string / number / boolean / object	—	—
label	label of option, same as value if omitted	string/number	—	—
disabled	whether option is disabled	boolean	—	false

Option Slots

Name	Description
—	customize default content

Methods

Method	Description	Parameters
focus	focus the Input component	-
blur	blur the Input component, and hide the dropdown	-