Form Radio ​

Individual radios ​

<template>
  <div class="my-2">
    <label>Individual radios</label>
  </div>

  <div>
    <BFormRadio v-model="individualSelected" name="some-radios" value="A">Option A </BFormRadio>
    <BFormRadio v-model="individualSelected" name="some-radios" value="B">Option B </BFormRadio>
  </div>

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

<script setup lang="ts">
const individualSelected = ref()
</script>

Grouped radios ​

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

<template>
  <div class="my-2">
    <label>Radios using options</label>
  </div>

  <div>
    <BFormRadioGroup
      id="radio-group-1"
      v-model="groupedSelected"
      :options="groupedOptions"
      name="radio-options"
    />
  </div>

  <div class="my-2">
    <label>Radios using sub-components</label>
  </div>

  <div>
    <BFormRadioGroup id="radio-group-2" v-model="groupedSelected" name="radio-sub-component">
      <BFormRadio value="first">Toggle this custom radio</BFormRadio>
      <BFormRadio value="second">Or toggle this other custom radio</BFormRadio>
      <BFormRadio value="third" disabled>This one is Disabled</BFormRadio>
      <BFormRadio :value="{fourth: 4}">This is the 4th radio</BFormRadio>
    </BFormRadioGroup>
  </div>

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

<script setup lang="ts">
const groupedOptions = [
  {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}},
]

const groupedSelected = ref('first')
</script>

Feel free to mix and match options prop and BFormRadio in BFormRadioGroup. Manually placed BFormRadio 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 class="my-2">
    <label>Radios using options and slots</label>
  </div>

  <div>
    <BFormRadioGroup
      id="radio-slots"
      v-model="mixedGroupedSelected"
      :options="mixedGroupedOptions"
      name="radio-options-slots"
    >
      <template #first>
        <BFormRadio value="first">Toggle this custom radio from slot first</BFormRadio>
      </template>

      <BFormRadio :value="{fourth: 4}">This is the 4th radio</BFormRadio>
      <BFormRadio value="fifth">This is the 5th radio</BFormRadio>
    </BFormRadioGroup>
  </div>

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

<script setup lang="ts">
const mixedGroupedOptions = [
  {text: 'Or toggle this other custom radio', value: 'second'},
  {text: 'Third radio', value: 'third'},
]

const mixedGroupedSelected = ref('first')
</script>

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

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, bootstrap-vue-next 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, BootstrapVueNext 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>
  <BFormRadioGroup
    v-model="customFieldNameSelected"
    :options="customFieldNameOptions"
    class="mb-3"
    value-field="item"
    text-field="name"
    disabled-field="notEnabled"
  />

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

<script setup lang="ts">
const customFieldNameSelected = ref('A')

const customFieldNameOptions = [
  {item: 'A', name: 'Option A'},
  {item: 'B', name: 'Option B'},
  {item: 'D', name: 'Option C', notEnabled: true},
  {item: {d: 1}, name: 'Option D'},
]
</script>

Radio value and v-model ​

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

The v-model of both BFormRadio and BFormRadioGroup binds to the default modelValue 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 radio's value prop). 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, BFormRadioGroup generates inline radio inputs, while BFormRadio generates stacked radios. Set the prop stacked on BFormRadioGroup to make the radios appear one over the other, or when using radios not in a group, set the inline prop on BFormRadio to true to render them inline.

<template>
  <div class="my-2">
    <label>Inline radios (default)</label>
  </div>

  <div>
    <BFormRadioGroup
      v-model="inlineStackedSelected"
      :options="inlineStackedOptions"
      name="radio-inline"
    />
  </div>

  <div class="my-2">
    <label>Stacked radios</label>
  </div>

  <div>
    <BFormRadioGroup
      v-model="inlineStackedSelected"
      :options="inlineStackedOptions"
      name="radio-stacked"
      stacked
    />
  </div>

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

<script setup lang="ts">
const inlineStackedOptions = [
  {text: 'First radio', value: 'first'},
  {text: 'Second radio', value: 'second'},
  {text: 'Third radio', value: 'third'},
]

const inlineStackedSelected = ref('first')
</script>

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).

<BFormRadio name="radio-size" size="sm">Small</BFormRadio>
<BFormRadio name="radio-size">Default</BFormRadio>
<BFormRadio name="radio-size" size="lg">Large</BFormRadio>

Sizes can be set on individual BFormRadio components, or inherited from the size setting of BFormRadioGroup.

Note: Bootstrap v5.x does not natively support sizes for the custom radio control. However, bootstrap-vue-next 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 BFormRadioGroup. Set the button variant by setting the button-variant prop to one of the standard Bootstrap button variants (see BButton 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 class="my-2">
    <label>Button style radios</label>
  </div>

  <div>
    <BFormRadioGroup
      v-model="buttonsSelected"
      :options="buttonsOptions"
      name="radios-btn-default"
      buttons
    />
  </div>

  <div class="my-2">
    <label>Button style radios with outline-primary variant and size lg</label>
  </div>

  <div>
    <BFormRadioGroup
      v-model="buttonsSelected"
      :options="buttonsOptions"
      button-variant="outline-primary"
      size="lg"
      name="radios-btn-outline"
      buttons
    />
  </div>

  <div class="my-2">
    <label>Stacked button style radios</label>
  </div>

  <div>
    <BFormRadioGroup
      v-model="buttonsSelected"
      :options="buttonsOptions"
      name="radios-btn-stacked"
      buttons
      stacked
    />
  </div>

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

<script setup lang="ts">
const buttonsOptions = [
  {text: 'Radio 1', value: 'radio1'},
  {text: 'Radio 3', value: 'radio2'},
  {text: 'Radio 3 (disabled)', value: 'radio3', disabled: true},
  {text: 'Radio 4', value: 'radio4'},
]

const buttonsSelected = ref('radio1')
</script>

Reverse ​

Use the reverse prop to put your radio buttons on the opposite side of the label.

<BFormRadio reverse>Reverse checkbox</BFormRadio>
<BFormRadio reverse disabled>Disabled reverse checkbox</BFormRadio>

Without Labels ​

In order to omit labels as described in the bootstrap documentation just leave the default slot empty. Remember to still provide some form of accessible name for assistive technologies (for instance, using aria-label).

  <BFormRadio></BFormRadio>
  <BFormRadio disabled></BFormRadio>

Non-custom style radio inputs (plain) ​

You can have BFormRadio and BFormRadioGroup render a browser native-styled radio input by setting the plain prop.

<template>
  <div class="my-2">
    <label>Plain inline radios</label>
  </div>

  <div>
    <BFormRadioGroup v-model="plainSelected" :options="plainOptions" name="plain-inline" plain />
  </div>

  <div class="my-2">
    <label>Plain stacked radios</label>
  </div>

  <div>
    <BFormRadioGroup v-model="plainSelected" :options="plainOptions" name="plain-stacked" plain />
  </div>

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

<script setup lang="ts">
const plainOptions = [
  {text: 'First radio', value: 'first'},
  {text: 'Second radio', value: 'second'},
  {text: 'Third radio', value: 'third'},
]

const plainSelected = ref('first')
</script>

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

Required constraint ​

When using individual BFormRadio components (not in a BFormRadioGroup), and you want the radio(s) to be required in your form, you must provide a name on each BFormRadio in order for the required constraint to work. All BFormRadio 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. BFormRadioGroup will automatically generate a unique input name if one is not provided on the group.

Autofocus ​

When the autofocus prop is set on BFormRadio, the input will be auto-focused when it is inserted (i.e. mounted) into the document or re-activated when inside a Vue KeepAlive 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 is 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 BFormRadio, 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>
  <BFormRadioGroup
    v-model="contextualSelected"
    :options="contextualOptions"
    :state="contextualState"
    name="radio-validation"
  />

  <div class="text-danger" v-if="!contextualState">Please select one</div>
  <div class="text-success" v-if="contextualState">Thank you</div>
</template>

<script setup lang="ts">
const contextualOptions = [
  {text: 'First radio', value: 'first'},
  {text: 'Second radio', value: 'second'},
  {text: 'Third radio', value: 'third'},
]

const contextualSelected = ref()

const contextualState = computed(() => !!contextualSelected.value)
</script>

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. BFormInvalidFeedback). Specifically for assistive technologies, invalid form controls can also be assigned an aria-invalid="true" attribute (see below).

ARIA aria-invalid attribute ​

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