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:
value
The selected value which will be set onv-model
disabled
Disables item for selectiontext
Display text, orhtml
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.
<!-- 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.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 detectedtrue
The 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 -->