Form Radio Inputs

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

Individual radios

<template>
  <div>
    <b-form-group label="Individual radios" v-slot="{ ariaDescribedby }">
      <b-form-radio v-model="selected" :aria-describedby="ariaDescribedby" name="some-radios" value="A">Option A</b-form-radio>
      <b-form-radio v-model="selected" :aria-describedby="ariaDescribedby" name="some-radios" value="B">Option B</b-form-radio>
    </b-form-group>

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

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

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

Grouped radios

The individual radio inputs in <b-form-radio-group> can be specified via the options prop, or via manual placement of the <b-form-radio> sub component. When using manually placed <b-form-radio> components within a <b-form-radio-group>, they will inherit most props and the v-model from the <b-form-radio-group>.

<template>
  <div>
    <b-form-group label="Radios using options" v-slot="{ ariaDescribedby }">
      <b-form-radio-group
        id="radio-group-1"
        v-model="selected"
        :options="options"
        :aria-describedby="ariaDescribedby"
        name="radio-options"
      ></b-form-radio-group>
    </b-form-group>

    <b-form-group label="Radios using sub-components" v-slot="{ ariaDescribedby }">
      <b-form-radio-group
        id="radio-group-2"
        v-model="selected"
        :aria-describedby="ariaDescribedby"
        name="radio-sub-component"
      >
        <b-form-radio value="first">Toggle this custom radio</b-form-radio>
        <b-form-radio value="second">Or toggle this other custom radio</b-form-radio>
        <b-form-radio value="third" disabled>This one is Disabled</b-form-radio>
        <b-form-radio :value="{ fourth: 4 }">This is the 4th radio</b-form-radio>
      </b-form-radio-group>
    </b-form-group>

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

<script>
  export default {
    data() {
      return {
        selected: 'first',
        options: [
          { text: 'Toggle this custom radio', value: 'first' },
          { text: 'Or toggle this other custom radio', value: 'second' },
          { text: 'This one is Disabled', value: 'third', disabled: true },
          { text: 'This is the 4th radio', value: { fourth: 4 } }
        ]
      }
    }
  }
</script>

<!-- b-form-radio-group.vue -->

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

<template>
  <div>
    <b-form-group label="Radios using options and slots" v-slot="{ ariaDescribedby }">
      <b-form-radio-group
        id="radio-slots"
        v-model="selected"
        :options="options"
        :aria-describedby="ariaDescribedby"
        name="radio-options-slots"
      >
        <!-- Radios in this slot will appear first -->
        <template #first>
          <b-form-radio value="first">Toggle this custom radio from slot first</b-form-radio>
        </template>

        <!-- Radios in the default slot will appear after any option generated radios -->
        <b-form-radio :value="{ fourth: 4 }">This is the 4th radio</b-form-radio>
        <b-form-radio value="fifth">This is the 5th radio</b-form-radio>
      </b-form-radio-group>
    </b-form-group>

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

<script>
  export default {
    data() {
      return {
        selected: '',
        options: [
          { text: 'Or toggle this other custom radio', value: 'second' },
          { text: 'Third radio', value: 'third' }
        ]
      }
    }
  }
</script>

<!-- b-form-radio-group-slot.vue -->

Radio group options array

options can be an array of strings or objects. 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.

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.

Internally, BootstrapVue 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 },
  { html: '<b>Item</b> 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, 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-radio-group
      v-model="selected"
      :options="options"
      class="mb-3"
      value-field="item"
      text-field="name"
      disabled-field="notEnabled"
    ></b-form-radio-group>
    <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-radio-group-options-fields.vue -->

Radio value and v-model

<b-form-radio> components do not have a value by default. You must explicitly supply a value via the value prop on <b-form-radio>. This value will be sent to the v-model when the radio is checked.

The v-model of both <b-form-radio> and <b-form-radio-group> binds to the checked prop. To pre-check a radio, you must set the v-model value to the one of the radio's value (i.e. must match the value of specified on one of the the radio's value prop). Do not use the checked prop directly. Each radio in a radio group must have a unique value.

Radios support values of many types, such as a string, boolean, number, or a plain object.

Inline or stacked radios

By default <b-form-radio-group> generates inline radio inputs, while <b-form-radio> generates stacked radios. Set the prop stacked on <b-form-radio-group> to make the radios appear one over the other, or when using radios not in a group, set the inline prop on b-form-radio to true to render them inline.

<template>
  <div>
    <b-form-group label="Inline radios (default)" v-slot="{ ariaDescribedby }">
      <b-form-radio-group
        v-model="selected"
        :options="options"
        :aria-describedby="ariaDescribedby"
        name="radio-inline"
      ></b-form-radio-group>
    </b-form-group>

    <b-form-group label="Stacked radios" v-slot="{ ariaDescribedby }">
      <b-form-radio-group
        v-model="selected"
        :options="options"
        :aria-describedby="ariaDescribedby"
        name="radios-stacked"
        stacked
      ></b-form-radio-group>
    </b-form-group>

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

<script>
  export default {
    data() {
      return {
        selected: 'first',
        options: [
          { text: 'First radio', value: 'first' },
          { text: 'Second radio', value: 'second' },
          { text: 'Third radio', value: 'third' }
        ]
      }
    }
  }
</script>

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

Control sizing

Use the size prop to control the size of the radio. The default size is medium. Supported size values are sm (small) and lg (large).

<div>
  <b-form-radio name="radio-size" size="sm">Small</b-form-radio>
  <b-form-radio name="radio-size">Default</b-form-radio>
  <b-form-radio name="radio-size" size="lg">Large</b-form-radio>
</div>

<!-- form-radio-sizes.vue -->

Sizes can be set on individual <b-form-radio> components, or inherited from the size setting of <b-form-radio-group>.

Note: Bootstrap v4.x does not natively support sizes for the custom radio control. However, BootstrapVue includes custom SCSS/CSS that adds support for sizing the custom radios.

Button style radios

Render radios with the look of buttons by setting the prop buttons to true on <b-form-radio-group>. Set 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.

The buttons prop has precedence over plain, and button-variant has no effect if buttons is not set.

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

<template>
  <div>
    <b-form-group label="Button style radios" v-slot="{ ariaDescribedby }">
      <b-form-radio-group
        id="btn-radios-1"
        v-model="selected"
        :options="options"
        :aria-describedby="ariaDescribedby"
        name="radios-btn-default"
        buttons
      ></b-form-radio-group>
    </b-form-group>

    <b-form-group
      label="Button style radios with outline-primary variant and size lg"
      v-slot="{ ariaDescribedby }"
    >
      <b-form-radio-group
        id="btn-radios-2"
        v-model="selected"
        :options="options"
        :aria-describedby="ariaDescribedby"
        button-variant="outline-primary"
        size="lg"
        name="radio-btn-outline"
        buttons
      ></b-form-radio-group>
    </b-form-group>

    <b-form-group label="Stacked button style radios" v-slot="{ ariaDescribedby }">
      <b-form-radio-group
        id="btn-radios-3"
        v-model="selected"
        :options="options"
        :aria-describedby="ariaDescribedby"
        name="radio-btn-stacked"
        buttons
        stacked
      ></b-form-radio-group>
    </b-form-group>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        selected: 'radio1',
        options: [
          { text: 'Radio 1', value: 'radio1' },
          { text: 'Radio 3', value: 'radio2' },
          { text: 'Radio 3 (disabled)', value: 'radio3', disabled: true },
          { text: 'Radio 4', value: 'radio4' }
        ]
      }
    }
  }
</script>

<!-- b-form-radio-buttons.vue -->

Non-custom style radio inputs (plain)

You can have <b-form-radio> and <b-form-radio-group> render a browser native-styled radio input by setting the plain prop.

<template>
  <div>
    <b-form-group label="Plain inline radios" v-slot="{ ariaDescribedby }">
      <b-form-radio-group
        v-model="selected"
        :options="options"
        :aria-describedby="ariaDescribedby"
        name="plain-inline"
        plain
      ></b-form-radio-group>
    </b-form-group>

    <b-form-group label="Plain stacked radios" v-slot="{ ariaDescribedby }">
      <b-form-radio-group
        v-model="selected"
        :options="options"
        :aria-describedby="ariaDescribedby"
        name="plain-stacked"
        plain
        stacked
      ></b-form-radio-group>
    </b-form-group>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        selected: 'first',
        options: [
          { text: 'First radio', value: 'first' },
          { text: 'Second radio', value: 'second' },
          { text: 'Third radio', value: 'third' }
        ]
      }
    }
  }
</script>

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

Note: plain will have no effect if buttons/button is set.

Required constraint

When using individual <b-form-radio> components (not in a <b-form-radio-group>), and you want the radio(s) to be required in your form, you must provide a name on each <b-form-radio> in order for the required constraint to work. All <b-form-radio> components tied to the same v-model must have the same name.

The name is required in order for Assistive Technologies (such as screen readers, and keyboard only users) to know which radios belong to the same form variable (the name also automatically enables native browser keyboard navigation), hence required will only work if name is set. <b-form-radio-group> will automatically generate a unique input name if one is not provided on the group.

Autofocus

When the autofocus prop is set on <b-form-radio>, the input 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 input, nor can it tell when the input 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-radio>, set the state prop to false (for invalid), true (for valid), or null (no validation state).

Note: Contextual state is not supported for radios rendered in buttons mode.

Contextual state with feedback example

<template>
  <div>
    <b-form-radio-group v-model="value" :options="options" :state="state" name="radio-validation">
      <b-form-invalid-feedback :state="state">Please select one</b-form-invalid-feedback>
      <b-form-valid-feedback :state="state">Thank you</b-form-valid-feedback>
    </b-form-radio-group>
  </div>
</template>

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

<!-- b-form-radio-validation.vue -->

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

Supported aria-invalid values are:

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

aria-invalid is automatically set to true if the state prop is false.

Component reference

<b-form-radio-group>

Component aliases

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

  • <b-radio-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
(Click to sort Ascending)
Type
(Click to sort Ascending)
Default
Description
aria-invalid
Boolean or StringfalseSets the 'aria-invalid' attribute value on the wrapper element. When not provided, the 'state' prop will control the attribute
autofocus
BooleanfalseWhen 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
button-variant
StringSpecifies the Bootstrap contextual color theme variant the apply to the button style radios
buttons
BooleanfalseWhen set, renderes the radios in this group with button styling
checked
v-model
AnyThe current value of the checked radio in the group
disabled
BooleanfalseWhen 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
StringID 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
StringUsed to set the `id` attribute on the rendered content, and used as the base to generate any additional element IDs as needed
name
StringSets the value of the `name` attribute on the form control
options
Array or Object[]Array of items to render in the component
plain
BooleanfalseRender the form control in plain mode, rather than custom styled mode
required
BooleanfalseAdds the `required` attribute to the form control
size
StringSet the size of the component's appearance. 'sm', 'md' (default), or 'lg'
stacked
BooleanfalseWhen set, renders the radio group in stacked mode
state
BooleannullControls 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
validated
BooleanfalseWhen set, adds the Bootstrap class 'was-validated' to the group wrapper
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
checkedinput

Slots

Name
Description
default Content (form radios) to place in the form radio group
first Slot to place b-form-radio's so that they appear before radios generated from options prop

Events

Event
Arguments
Description
change
  1. checked - Current selected Value of radio group
Emitted when selected value is changed due to user interaction
input
  1. checked - Current selected Value of radio group
Emitted when the selected value is changed

<b-form-radio>

Component aliases

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

  • <b-radio>

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-label
StringSets the value of `aria-label` attribute on the rendered element
aria-labelledby
StringThe ID of the element that provides a label for this component. Used as the value for the `aria-labelledby` attribute
autofocus
BooleanfalseWhen 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
button
BooleanfalseWhen set, renders the radio with the appearance of a button
button-variant
StringApplies on of Bootstrap's theme colors when in 'button' mode
checked
v-model
AnynullThe current value of the radio(s)
disabled
BooleanfalseWhen set to `true`, disables the component's functionality and places it in a disabled state
form
StringID of the form that the form control belongs to. Sets the `form` attribute on the control
id
StringUsed to set the `id` attribute on the rendered content, and used as the base to generate any additional element IDs as needed
inline
BooleanfalseWhen set, renders the radio as an inline element rather than as a 100% width block
name
StringSets the value of the `name` attribute on the form control
plain
BooleanfalseRender the form control in plain mode, rather than custom styled mode
required
BooleanfalseAdds the `required` attribute to the form control
size
StringSet the size of the component's appearance. 'sm', 'md' (default), or 'lg'
state
BooleannullControls the validation state appearance of the component. `true` for valid, `false` for invalid, or `null` for no validation state
value
AnyValue returned when this radio is checked

v-model

Property
Event
checkedinput

Slots

Name
Description
default Content to place in the form radio

Events

Event
Arguments
Description
change
  1. checked - Current selected Value of radio group
Emitted when selected value is changed due to user interaction
input
  1. checked - Current selected Value of radio group
Emitted when the selected value is changed

Importing individual components

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

Component
Named Export
Import Path
<b-form-radio-group>BFormRadioGroupbootstrap-vue
<b-form-radio>BFormRadiobootstrap-vue

Example:

import { BFormRadioGroup } from 'bootstrap-vue'
Vue.component('b-form-radio-group', BFormRadioGroup)

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
FormRadioPluginbootstrap-vue

Example:

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