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>`

View source

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

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 `String`	`false`	Sets the 'aria-invalid' attribute value on the wrapper element. When not provided, the 'state' prop will control the attribute
`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
`button-variant`	`String`		Specifies the Bootstrap contextual color theme variant the apply to the button style radios
`buttons`	`Boolean`	`false`	When set, renderes the radios in this group with button styling
`checked` v-model	`Any`		The current value of the checked radio in the group
`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
`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
`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
`size`	`String`		Set the size of the component's appearance. 'sm', 'md' (default), or 'lg'
`stacked`	`Boolean`	`false`	When set, renders the radio group in stacked mode
`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
`validated`	`Boolean`	`false`	When 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
`checked`	`input`

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`	`checked` - Current selected Value of radio group	Emitted when selected value is changed due to user interaction
`input`	`checked` - Current selected Value of radio group	Emitted when the selected value is changed

`<b-form-radio>`

View source

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

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`	`String`		Sets the value of `aria-label` attribute on the rendered element
`aria-labelledby`	`String`		The ID of the element that provides a label for this component. Used as the value for the `aria-labelledby` attribute
`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
`button`	`Boolean`	`false`	When set, renders the radio with the appearance of a button
`button-variant`	`String`		Applies on of Bootstrap's theme colors when in 'button' mode
`checked` v-model	`Any`	`null`	The current value of the radio(s)
`disabled`	`Boolean`	`false`	When set to `true`, disables the component's functionality and places it in a disabled state
`form`	`String`		ID of the form that the form control belongs to. Sets the `form` attribute on the control
`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
`inline`	`Boolean`	`false`	When set, renders the radio as an inline element rather than as a 100% width block
`name`	`String`		Sets the value of the `name` attribute on the form control
`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
`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
`value`	`Any`		Value returned when this radio is checked

`v-model`

Property	Event
`checked`	`input`

Slots

Name	Description
`default`	Content to place in the form radio

Events

Event	Arguments	Description
`change`	`checked` - Current selected Value of radio group	Emitted when selected value is changed due to user interaction
`input`	`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>`	`BFormRadioGroup`	`bootstrap-vue`
`<b-form-radio>`	`BFormRadio`	`bootstrap-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
`FormRadioPlugin`	`bootstrap-vue`

Example:

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

Individual radios

Grouped radios

Radio group options array

Options as an array of objects

Changing the option field names

Radio value and v-model

Inline or stacked radios

Control sizing

Button style radios

Non-custom style radio inputs (plain)

Required constraint

Autofocus

Contextual states

Contextual state with feedback example

Conveying contextual validation state to assistive technologies and colorblind users

ARIA aria-invalid attribute

Component reference

Component aliases

Properties

v-model

Slots

Events

Component aliases

Properties

v-model

Slots

Events

Importing individual components

Importing as a Vue.js plugin

ARIA `aria-invalid` attribute

`v-model`

`v-model`