Checkbox / radio

Component covering both checkboxes and radios.

NOTE

Please be sure to read the Basic concepts part of the documentation first.

Basic usage

This page documents the component bt-form-checkbox that covers both checkboxes and radios.

The logic behind this component is to consider that a checkbox and a radio button are the same thing, the only difference is that one allow the selection of multiple values, and the other doesn't.

So in a sense, a radio is a group of checkboxes that only allow one of them to be selected at a time.

Here's an example of checkboxes:

And the equivalent with radios:

NOTE

There are 2 differences to note:

In the first example, hobbies is an array, while hobby in the second example is not.
In the second example, each checkbox has the group hobby. That's what make them radios.

States

Here a demo that illustrates the different states checkboxes and radios can take:

TIP

By default, errors are "floating" (meaning they show as a popover), you can make them show under the field by setting floating-errors to false.

But, the setting is ignored if the control is inside an addon of another component. In this case the errors will always be floating.

Help text

You can add a little help text below the checkbox via the help slot:

TIP

By default, the help text is not "floating", you can make them float by setting floating-help to true.

But, the setting is ignored if the control is inside an addon of another component. In this case the help text will always be floating.

Indeterminate

A checkbox can take an indeterminate state by setting the indeterminate prop to true:

Radio

To create a radio button, simply give a group to the checkboxes:

Mix radio groups

You can give the same array (for v-model) or control to any number of radios, even with different groups, each group will add a single value to the result:

Mix checkboxes and radios

You can also mix checkboxes and radios in a single control/v-model:

Debug

If you add the debug attribute to the component, a little icon shows on the right, allowing you to inspect the whole viewData object exposed by the component.

If you don't know what the viewData object is, please refer to this part of the documentation.

Props

Method	Description	Default
v-model	Bidirectional binding for the value of the control.	`undefined`
value	The original value given by the end-user through the html element.	`undefined`
checked	If `true` or `false` the checkbox will be checked or unchecked respectively upon initialization or when a change is detected on the prop. If `null`, the checked status will be given by the `FormControl`.	`null`
checked-value	The value to set to the control when the checkbox is checked.	`true`
unchecked-value	The value to set to the control when the checkbox is unchecked.	`undefined`
indeterminate	If `true`, force the checkbox to be visually indeterminate. The indeterminate status will be lost each time the checkbox changes state, and will be restored if the prop changes to `true`.	`false`
uncheckable	If `true` a radio group can be totally unchecked.	`false`
group	If defined the component will behave like a radio button. Only one value can be selected for a given group. If `null` the component will behave like a checkbox.	`null`
label	The label of the field. Overridden by the `default` slot.	`null`
placeholder	A placeholder value to show when there is no value selected.	`null`
help	A help text to show to the user. Overridden by the `help` slot.	`null`
floating-label	If `true` the label will float above the control and act as a placeholder is there is none.	`true`
floating-errors	If `true` the errors will appear as an icon on the right side of the input that shows a popover. This value is overridden to `true` internally if the control is in a group to preserve layout integrity.	`true`
floating-help	If `true` the help text will appear as an icon on the right side of the input that shows a popover. This value is overridden to `true` internally if the control is in a group to preserve layout integrity.	`false`
required	If `true`, a little asterisk extra is shown, indicating to the user that the field is mandatory.	`false`
disabled	For external control of the `disabled` state of the control.	`false`
busy	For external control of the `busy` state of the control.	`false`
debug	If `true`, show the debug overlay.	`false`
tab-index	HTML tab index (for keyboard navigation).	`0`

Slots

Name Description

Name	Description
default or label	Defines the label of the field. This slot takes priority over the `label` prop. Props: none
help	Defines the help text of the field. This slot takes priority over the `help` prop. Props: none

default or label

Defines the label of the field. This slot takes priority over the label prop.

Props: none

help

Defines the help text of the field. This slot takes priority over the help prop.

Props: none

Theming

Below the list of all CSS variables and selectors available to customize the appearance of the component. If you're not familiar on how the theming works, please refer to the VueThemes documentation.

Variables

Variable	Default	Comment
fontFamily	`var(--bt-font-family-base)`	-
fontSize	`var(--bt-font-size-base)`	-
fontWeight	`var(--bt-font-weight-normal)`	-
textColor	`var(--bt-text-color-base)`	-
backgroundColor	`var(--bt-color-white)`	-
backgroundDisabledColor	Same as `backgroundColor`	-
borderColor	`var(--bt-color-gray-200)`	-
borderRadius	`var(--bt-border-radius-base)`	-
borderWidth	`var(--bt-border-width-base)`	-
borderStyle	`var(--bt-border-style-base)`	-
borderFocusWidth	Same as `borderWidth`	-
borderFocusColor	`var(--bt-color-primary)`	-
borderErrorWidth	Same as `borderWidth`	-
borderErrorColor	`var(--bt-color-red-500)`	-
borderDisabledColor	`var(--bt-color-gray-200)`	-
helpTextColor	`var(--bt-text-color-light)`	-
helpFontSize	`var(--bt-font-size-sm)`	-
errorTextColor	`var(--bt-color-red-500)`	-
errorFontSize	`var(--bt-font-size-sm)`	-
disabledOpacity	`0.5`	-
addonBackgroundColor	`var(--bt-color-gray-50)`	-
addonTextColor	`var(--bt-text-color-light)`	-
size	`1em`	-
borderRadius	`var(--bt-border-radius-base)`	-
backgroundColor	`transparent`	-
backgroundCheckedColor	`var(--bt-color-primary)`	-
outlineColor	`var(--bt-color-gray-300)`	-
outlineHoverColor	`var(--bt-color-primary)`	-
outlineFocusedColor	`var(--bt-color-primary)`	-
outlineCheckedColor	`var(--bt-color-primary)`	-
outlineWidth	`0`	-
outlineHoverWidth	`1px`	-
outlineFocusedWidth	`1px`	-
outlineCheckedWidth	`1px`	-
iconColor	`var(--bt-color-primary-contrast)`	-
errorColor	`var(--bt-color-red-500)`	-

Selectors

Name	Comment
root	The root container.
label	The container of the label.
help	The non floating help text container.
inputGroup	A container that only include the form field.
input	The actual form control.

Examples:

cssSelectors: {
    input: {
        background: '...'
    },
    help: {
        color: '...'
    }
}

# Checkbox / radio

# Basic usage

# States

# Help text

# Indeterminate

# Radio

# Mix radio groups

# Mix checkboxes and radios

# Debug

# Props

# Slots

# Theming

# Variables

# Selectors