Form Checkbox Inputs

For cross browser consistency, <b-form-checkbox-group> and <b-form-checkbox> use Bootstrap's custom checkbox input to replace the browser default checkbox input. It is built on top of semantic and accessible markup, so it is a solid replacement for the default checkbox input.

Example 1: Single checkbox

<template>
  <div>
    <b-form-checkbox
      id="checkbox1"
      v-model="status"
      value="accepted"
      unchecked-value="not_accepted"
    >
      I accept the terms and use
    </b-form-checkbox>

    <div>State: <strong>{{ status }}</strong></div>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        status: 'not_accepted'
      }
    }
  }
</script>

<!-- b-form-checkbox.vue -->

Example 2: Multiple choice checkboxes

<template>
  <div>
    <b-form-group label="Using options array:">
      <b-form-checkbox-group
        id="checkboxes1"
        name="flavour1"
        v-model="selected"
        :options="options"
      />
    </b-form-group>

    <b-form-group label="Using sub-components:">
      <b-form-checkbox-group id="checkboxes2" name="flavour2" v-model="selected">
        <b-form-checkbox value="orange">Orange</b-form-checkbox>
        <b-form-checkbox value="apple">Apple</b-form-checkbox>
        <b-form-checkbox value="pineapple">Pineapple</b-form-checkbox>
        <b-form-checkbox value="grape">Grape</b-form-checkbox>
      </b-form-checkbox-group>
    </b-form-group>

    <div>Selected: <strong>{{ selected }}</strong></div>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        selected: [], // Must be an array reference!
        options: [
          { text: 'Orange', value: 'orange' },
          { text: 'Apple', value: 'apple' },
          { text: 'Pineapple', value: 'pineapple' },
          { text: 'Grape', value: 'grape' }
        ]
      }
    }
  }
</script>

<!-- b-form-checkbox-multiple.vue -->

Feel free to mix and match options prop and <b-form-checkbox> in <b-form-checkbox-group>. Manually placed <b-form-checkbox> inputs will appear below any checkbox inputs generated by the options prop. To have them appear above the inputs generated by options, place them in the named slot first.

Checkbox group options array

Please see options in <b-form-select> docs for details on passing options (value array) to <b-form-checkbox-group>.

Inline and Stacked checkboxes

<b-form-checkbox-group> components render inline checkboxes by default, while <b-form-checkbox> renders block-level (stacked) checkboxes.

Set the prop stacked on <b-form-checkbox-group> to place each form control one over the other, or if using individual checkboxes not inside a <b-form-checkbox-group>, set the inline prop on <b-form-checkbox>.

<template>
  <div>
    <b-form-group label="Form-checkbox-group inline checkboxes (default)">
      <b-form-checkbox-group v-model="selected" name="flavour1" :options="options" />
    </b-form-group>

    <b-form-group label="Form-checkbox-group stacked checkboxes">
      <b-form-checkbox-group stacked v-model="selected" name="flavour2" :options="options" />
    </b-form-group>

    <b-form-group label="Individual stacked checkboxes (default)">
      <b-form-checkbox
        v-for="option in options"
        v-model="selected"
        :key="option.value"
        :value="option.value"
        name="flavour3"
      >
        {{ option.text }}
      </b-form-checkbox>
    </b-form-group>

    <b-form-group label="Individual inline checkboxes">
      <b-form-checkbox
        v-for="option in options"
        v-model="selected"
        :key="option.value"
        :value="option.value"
        name="flavour4"
        inline
      >
        {{ option.text }}
      </b-form-checkbox>
    </b-form-group>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        selected: [], // Must be an array reference!
        options: [
          { text: 'Orange', value: 'orange' },
          { text: 'Apple', value: 'apple' },
          { text: 'Pineapple', value: 'pineapple' },
          { text: 'Grape', value: 'grape' }
        ]
      }
    }
  }
</script>

<!-- b-form-checkbox-stacked.vue -->

Checkbox values and v-model

By default, <b-form-checkbox> value will be true when checked and false when unchecked. You can customize the checked and unchecked values by specifying the value and unchecked-value properties, respectively.

The v-model binds to the checked prop. When you have multiple checkboxes that bind to a single data state variable, you must provide an array reference ([]) to your v-model. Do not use the checked prop directly.

Note that when v-model is bound to multiple checkboxes (i.e an array ref), the unchecked-value is not used. Only the value(s) of the checked checkboxes will be returned in the v-model bound array. You should provide a unique value for each checkbox's value prop (the default of true will not work when bound to an array)

To pre-check any radios, set the v-model to the value(s) of the checks that you would like pre-selected.

When placing individual <b-form-checkbox> components within a <b-form-checkbox-group>, most props and the v-model are inherited from the <b-form-checkbox-group>.

Multiple checkboxes and accessibility

When binding multiple checkboxes together, you should set the name prop to the same value for all <b-form-checkbox>s in the group individually or via the name prop of <b-form-checkbox-group>. This will inform users of assistive technologies that the checkboxes are related.

Whenever using multiple checkboxes, it is recommended that the checkboxes be placed in a <b-form-group> component to associate a label with the entire group of checkboxes. See examples above.

Button style checkboxes

You can optionally render checkboxes to appear as buttons, either individually, or in a group.

Button style checkboxes will have the class .active automatically applied to the label when they are in the checked state.

Individual checkbox button style

A single checkbox can be rendered with a button appearance by setting the prop button to true

Change the button variant by setting the button-variant prop to one of the standard Bootstrap button variants (see <b-button> for supported variants). The default variant is secondary.

<template>
  <div>
    <b-form-checkbox button v-model="checked1" name="check-button">
      Button Checkbox <b>(Checked: {{ checked1 }})</b>
    </b-form-checkbox>
    <b-form-checkbox button v-model="checked2" name="check-button" button-variant="info">
      Button Checkbox <b>(Checked: {{ checked2 }})</b>
    </b-form-checkbox>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        checked1: false,
        checked2: false
      }
    }
  }
</script>

<!-- b-form-checkbox-button.vue -->

The inline prop has no effect on individual button-style checkboxes.

Grouped button style checkboxes

Render groups of checkboxes with the look of a button-group by setting the prop buttons on <b-form-checkbox-group>. Change the button variant by setting the button-variant prop to one of the standard Bootstrap button variants (see <b-button> for supported variants). The default button-variant is secondary.

<template>
  <div>
    <b-form-group label="Button-group style checkboxes">
      <b-form-checkbox-group buttons v-model="selected" name="buttons1" :options="options" />
    </b-form-group>

    <b-form-group label="Button-group style checkboxes with variant primary and large buttons">
      <b-form-checkbox-group
        v-model="selected"
        buttons
        button-variant="primary"
        size="lg"
        name="buttons2"
        :options="options"
      />
    </b-form-group>

    <b-form-group label="Stacked (vertical) button-group style checkboxes">
      <b-form-checkbox-group buttons v-model="selected" stacked :options="options" />
    </b-form-group>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        selected: [], // Must be an array reference!
        options: [
          { text: 'Orange', value: 'orange' },
          { text: 'Apple', value: 'apple' },
          { text: 'Pineapple', value: 'pineapple' },
          { text: 'Grape', value: 'grape' }
        ]
      }
    }
  }
</script>

<!-- b-form-checkbox-button-group.vue -->

Switch style checkboxes

Switch styling is supported on <b-form-checkbox> and <b-form-checkbox-group> components.

Note: If the checkbox is in button mode, switch mode will have no effect.

Individual checkbox switch style

A single checkbox can be rendered with a switch appearance by setting the prop switch to true

<template>
  <div>
    <b-form-checkbox switch v-model="checked" name="check-button">
      Switch Checkbox <b>(Checked: {{ checked }})</b>
    </b-form-checkbox>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        checked: false
      }
    }
  }
</script>

<!-- b-form-checkbox-switch.vue -->

Grouped switch style checkboxes

Render groups of checkboxes with the look of a switches by setting the prop switches on <b-form-checkbox-group>.

<template>
  <div>
    <b-form-group label="Inline switch style checkboxes">
      <b-form-checkbox-group switches v-model="selected" name="switches1" :options="options" />
    </b-form-group>

    <b-form-group label="Stacked (vertical) switch style checkboxes">
      <b-form-checkbox-group switches v-model="selected" stacked :options="options" />
    </b-form-group>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        selected: [], // Must be an array reference!
        options: [
          { text: 'Red', value: 'red' },
          { text: 'Green', value: 'green' },
          { text: 'Yellow (disabled)', value: 'yellow', disabled: true },
          { text: 'Blue', value: 'blue' }
        ]
      }
    }
  }
</script>

<!-- b-form-checkboxes-switch-group.vue -->

Non custom check inputs (plain)

You can have <b-form-checkbox-group> or <b-form-checkbox> render a browser native chechbox input by setting the plain prop.

<template>
  <div>
    <b-form-group label="Plain inline checkboxes">
      <b-form-checkbox-group plain v-model="selected" :options="options" />
    </b-form-group>

    <b-form-group label="Plain stacked checkboxes">
      <b-form-checkbox-group plain stacked v-model="selected" :options="options" />
    </b-form-group>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        selected: [], // Must be an array reference!
        options: [
          { text: 'Orange', value: 'orange' },
          { text: 'Apple', value: 'apple' },
          { text: 'Pineapple', value: 'pineapple' },
          { text: 'Grape', value: 'grape' }
        ]
      }
    }
  }
</script>

<!-- b-form-checkbox-plain.vue -->

Note: The plain prop has no effect when button or buttons is 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:

  • 'invalid' (or false) is great for when there’s a blocking or required field. A user must fill in this field properly to submit the form.
  • 'valid' (or true) 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

To apply one of the contextual state icons on <b-form-checkbox>, set the state prop to 'invalid' (or false), 'valid' (or true), or null.

Note: Contextual states are not supported when in button mode.

Contextual state and validation example

<template>
  <div>
    <b-form-checkbox-group v-model="value" :options="options" :state="state" name="checkboxValidation">
      <b-form-invalid-feedback :state="state">Please select two</b-form-invalid-feedback>
      <b-form-valid-feedback :state="state">Thank you</b-form-valid-feeback>
    </b-form-checkbox-group>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        value: [],
        options: [
          { text: 'First Check', value: 'first' },
          { text: 'Second Check', value: 'second' },
          { text: 'Third Check', value: 'third' }
        ]
      }
    },
    computed: {
      state() {
        return this.value.length === 2
      }
    }
  }
</script>

<!-- form-checkbox-validation.vue -->

Indeterminate (tri-state) support

Normally a checkbox input can only have two states: checked or unchecked. They can have any value, but they either submit that value (checked) or don't (unchecked) with a form submission (although BootstrapVue allows a value for the unchecked state on a single checkbox)

Visually, there are actually three states a checkbox can be in: checked, unchecked, or indeterminate.

The indeterminate state is visual only. The checkbox is still either checked or unchecked as a value. That means the visual indeterminate state masks the real value of the checkbox, so that better make sense in your UI!

<b-form-checkbox> supports setting this visual indeterminate state via the indeterminate prop (defaults to false). Clicking the checkbox will clear its indeterminate state. The indeterminate prop can be synced to the checkbox's state by v-binding the indeterminate prop with the .sync modifier.

Note: indeterminate styling is not supported in button or switch mode, nor is it supported in <b-form-checkbox-group> (multiple checkboxes).

Single Indeterminate checkbox:

<template>
  <div>
    <b-form-checkbox v-model="checked" :indeterminate.sync="indeterminate">
      Click me to see what happens
    </b-form-checkbox>

    <div class="mt-3">
      Checked: <strong>{{ checked }}</strong><br />
      Indeterminate: <strong>{{ indeterminate }}</strong>
    </div>

    <b-button @click="toggleIndeterminate">Toggle Indeterminate State</b-button>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        checked: true,
        indeterminate: true
      }
    },
    methods: {
      toggleIndeterminate() {
        this.indeterminate = !this.indeterminate
      }
    }
  }
</script>

<!-- b-form-checkbox-indeterminate.vue -->

Indeterminate checkbox use-case example:

<template>
  <div>
    <b-form-group>
      <template slot="label">
        <b>Choose your flavours:</b><br />
        <b-form-checkbox
          v-model="allSelected"
          :indeterminate="indeterminate"
          aria-describedby="flavours"
          aria-controls="flavours"
          @change="toggleAll"
        >
          {{ allSelected ? 'Un-select All' : 'Select All' }}
        </b-form-checkbox>
      </template>

      <b-form-checkbox-group
        id="flavors"
        stacked
        v-model="selected"
        name="flavs"
        :options="flavours"
        class="ml-4"
        aria-label="Individual flavours"
      />
    </b-form-group>

    <div>
      Selected: <strong>{{ selected }}</strong><br />
      All Selected: <strong>{{ allSelected }}</strong><br />
      Indeterminate: <strong>{{ indeterminate }}</strong>
    </div>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        flavours: ['Orange', 'Grape', 'Apple', 'Lime', 'Very Berry'],
        selected: [],
        allSelected: false,
        indeterminate: false
      }
    },
    methods: {
      toggleAll(checked) {
        this.selected = checked ? this.flavours.slice() : []
      }
    },
    watch: {
      selected(newVal, oldVal) {
        // Handle changes in individual flavour checkboxes
        if (newVal.length === 0) {
          this.indeterminate = false
          this.allSelected = false
        } else if (newVal.length === this.flavours.length) {
          this.indeterminate = false
          this.allSelected = true
        } else {
          this.indeterminate = true
          this.allSelected = false
        }
      }
    }
  }
</script>

<!-- b-form-checkbox-indeterminate-multiple.vue -->

Note: indeterminate is not supported in button mode, nor in multiple checkbox mode. Also pay attention that plain checkbox (i.e. with prop plain) also supports indeterminate state on Windows/Linux/Mac/Android, but not on iOS.

Indeterminate state and accessibility

Not all screen readers will convey the indeterminate state to screen reader users. So it is recommended to provide some form of textual feedback to the user (possibly by via the .sr-only class) if the indeterminate state has special contextual meaning in your application.

Form Checkbox Component Reference

<b-form-checkbox-group>

Component aliases

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

  • <b-checkbox-group>
  • <b-check-group>

Properties

PropertyTypeDefault Value
idString
nameString
disabledBoolean
requiredBooleanfalse
formString
validatedBooleanfalse
aria-invalidBoolean or Stringfalse
stackedBooleanfalse
plainBooleanfalse
buttonsBooleanfalse
button-variantStringsecondary
optionsArray or Object[]
value-fieldStringvalue
text-fieldStringtext
html-fieldStringhtml
disabled-fieldStringdisabled
sizeString
stateString or Boolean
switchesBooleanfalse
checkedString or Number or Object or Array or Boolean

Slots

SlotDescription
firstSlot to place b-form-checks so that they appear before checks generated from options prop

Events

EventArgumentsDescription
input
checked - Value of checkboxes. Value will be an array.
Emitted when the checked value is changed
change
checked - Value of checkboxes. Value will be an array.
Emitted when selected value(s) is changed due to user interaction

<b-form-checkbox>

Component aliases

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

  • <b-checkbox>
  • <b-check>

Properties

PropertyTypeDefault Value
valueObjecttrue
checkedString or Number or Object or Array or Boolean
inlineBooleanfalse
plainBooleanfalse
buttonBooleanfalse
button-variantString
idString
nameString
disabledBoolean
requiredBooleanfalse
formString
sizeString
stateString or Boolean
unchecked-valueObjectfalse
indeterminateBooleanfalse
switchBooleanfalse

Events

EventArgumentsDescription
input
checked - Value of checkbox(es). When bound to multiple checkboxes, value will be an array.
Emitted when the selected value(s) is changed
change
checked - Value of checkbox(es). When bound to multiple checkboxes, value will be an array.
Emitted when selected value(s) is changed due to user interaction

Importing individual Form Checkbox Components

ComponentImport Path
<b-form-checkbox-group>bootstrap-vue/es/components/form-checkbox-group/form-checkbox-group
<b-form-checkbox>bootstrap-vue/es/components/form-checkbox/form-checkbox

Example:

import BFormCheckboxGroup from 'bootstrap-vue/es/components/form-checkbox-group/form-checkbox-group'
Vue.component('b-form-checkbox-group', BFormCheckboxGroup)

Importing Form Checkbox as a Vue plugin

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

import { FormCheckbox } from 'bootstrap-vue/es/components'
Vue.use(FormCheckbox)