README.md
Form Radio
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:
valueThe selected value which will be set onv-modeldisabledDisables item for selectiontextDisplay text, orhtmlDisplay 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.
<!-- eslint-disable no-unused-vars -->
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:
<!-- eslint-disable no-unused-vars -->
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
<!-- eslint-disable no-unused-vars -->
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:
<!-- eslint-disable no-unused-vars -->
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 <code><b-button></code> 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.nullDisplays 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 detectedtrueThe value has failed validation.
aria-invalid is automatically set to true if the state prop is false.
<!-- Component reference added automatically from component package.json -->