Checkbox

The Checkbox input component uses HTML's native checkbox input. It can display one or many options to a user and is a great way to allow users to select multiple items from a list. The component supports single and multiple checkbox inputs. The component supports the W3C ARIA APG Checkbox Pattern. Use it with the Field component to access all the functionalities.

Examples

Base

By default the checkbox type will renders a single checkbox and uses boolean values. In order for a single checkbox to be checked the current value of the input must match the modelValue of that input (by default, a single checkbox uses true as the modelValue). The true and false value can be modified by using the true-value and false-value properties.

Show code

HTML

<section>
    <o-field>
        <o-checkbox label="Basic" />
    </o-field>

    <o-field>
        <o-checkbox v-model="checkbox">
            {{ checkbox }}
        </o-checkbox>
    </o-field>

    <o-field>
        <o-checkbox
            v-model="checkboxCustom"
            true-value="Yes"
            false-value="No">
            {{ checkboxCustom }}
        </o-checkbox>
    </o-field>

    <o-field>
        <o-checkbox :indeterminate="true"> Indeterminate </o-checkbox>
    </o-field>

    <o-field>
        <o-checkbox label="Disabled" disabled />
    </o-field>

    <o-field>
        <o-checkbox label="Required" required />
    </o-field>
</section>

JS

import { ref } from "vue";

const checkbox = ref(false);
const checkboxCustom = ref("Yes");

Multiple

When passing an array as modelValue prop, the value of the native-value property is added to the array if the box is checked.

Show code

HTML

<section>
    <o-field>
        <o-checkbox
            v-model="checkboxGroup"
            native-value="Silver"
            label="Silver" />

        <o-checkbox
            v-model="checkboxGroup"
            native-value="Flint"
            label="Flint" />

        <o-checkbox
            v-model="checkboxGroup"
            native-value="Vane"
            label="Vane" />

        <o-checkbox
            v-model="checkboxGroup"
            native-value="Billy"
            label="Billy"
            disabled />
    </o-field>

    <p><b>Selection:</b> {{ checkboxGroup }}</p>
</section>

JS

import { ref } from "vue";

const checkboxGroup = ref(["Flint"]);

Variants

Different styles can be achieved with the variant prop.

Show code

HTML

<section>
    <o-field>
        <o-checkbox :model-value="true" label="Default" />
    </o-field>

    <o-field>
        <o-checkbox :model-value="true" variant="primary" label="Primary" />
    </o-field>

    <o-field>
        <o-checkbox
            :model-value="true"
            variant="secondary"
            label="secondary" />
    </o-field>

    <o-field>
        <o-checkbox :model-value="true" variant="success" label="Success" />
    </o-field>

    <o-field>
        <o-checkbox :model-value="true" variant="info" label="Info" />
    </o-field>

    <o-field>
        <o-checkbox :model-value="true" variant="warning" label="Warning" />
    </o-field>

    <o-field>
        <o-checkbox :model-value="true" variant="danger" label="Danger" />
    </o-field>
</section>

Interminate

Checkboxes can only have two states: checked or unchecked. Visually, there are actually three states a checkbox can be in: checked, unchecked, or indeterminate. This third state can be achieved by setting the indeterminate prop.

Show code

HTML

<section>
    <o-field>
        <o-checkbox indeterminate label="Default" />
    </o-field>

    <o-field>
        <o-checkbox variant="primary" indeterminate label="Primary" />
    </o-field>

    <o-field>
        <o-checkbox variant="secondary" indeterminate label="Secondary" />
    </o-field>

    <o-field>
        <o-checkbox variant="success" indeterminate label="Success" />
    </o-field>

    <o-field>
        <o-checkbox variant="info" indeterminate label="Info" />
    </o-field>

    <o-field>
        <o-checkbox variant="warning" indeterminate label="Warning" />
    </o-field>

    <o-field>
        <o-checkbox variant="danger" indeterminate label="Danger" />
    </o-field>
</section>

Sizes

The component can be displayed in different sizes using the size prop.

Show code

HTML

<section>
    <o-field>
        <o-checkbox size="small" label="Small" />
    </o-field>

    <o-field>
        <o-checkbox label="Default" />
    </o-field>

    <o-field>
        <o-checkbox size="medium" label="Medium" />
    </o-field>

    <o-field>
        <o-checkbox size="large" label="Large" />
    </o-field>
</section>

Checkbox component

Select a single or grouped options.

<o-checkbox></o-checkbox>

Props

Prop name	Description	Type	Values	Default
autocomplete	Same as native autocomplete options to use in HTML5 validation	string	-	From config: checkbox: {   autocomplete: "off" }
customValidity	Custom HTML 5 validation error to set on the form control	string | ((currentValue: unknown, state: ValidityState) => string)	-	""
disabled	Same as native disabled	boolean	-	false
falseValue	Overrides the returned value when it's not checked	unknown	-
id	Same as native id. Also set the for label for o-field wrapper - default is an uuid.	string	-	useId()
indeterminate	Same as native indeterminate	boolean	-	false
label	Input label, unnecessary when default slot is used	string	-
v-model	The input value state, use v-model to make it two-way binding	unknown	-
name	Same as native name	string	-
nativeValue	Same as native value	unknown	-
override	Override existing theme classes completely	boolean	-
required	Same as native required	boolean	-	false
size	Size of the control	string	small, medium, large	From config: checkbox: {   size: undefined }
trueValue	Overrides the returned value when it's checked	unknown	-
useHtml5Validation	Enable HTML 5 native validation	boolean	-	From config: {   useHtml5Validation: true }
variant	Color of the control	string	primary, info, success, warning, danger, and any other custom color	From config: checkbox: {   variant: undefined }

Events

Event name	Properties	Description
update:model-value	value T | T[] - updated modelValue prop	modelValue prop two-way binding
input	value T | T[] - input value event Event - native event	on input change event
focus	event Event - native event	on input focus event
blur	event Event - native event	on input blur event
invalid	event Event - native event	on input invalid event

Slots

Name	Description	Bindings
default	Content slot, default is label prop

Class Inspector

Classes applied to the element:

How does the Class props inspector work?

Class props inspector is useful to see class props you want to use to customize Oruga components and how they change a component. You can click on Inspect button to find the exact element where a specific class prop acts.

In the Class props inspector there are other columns:

Class prop

This column contains the name of the Class prop you want to inspect.
If you find a name with a link ( ▷ classPropName) this refers to a subitem (e.g. Dropdown Item in Dropdown).

Description

This column contains the description of the Class prop you want to inspect.
👉 This icon indicates some warning, e.g. this Class prop is visible only on mobile.

Props

This column contains a list of props that activate the class, e.g. if a class prop contains disabled prop it means that only when the component has disabled prop.

Suffixes

This column contains all the possible suffixes that you'll receive if you use a function to customize your Class prop.

Class prop	Description	Props	Suffixes
rootClass	Class of the root element.
checkedClass	Class of the root element when checked.	modelValue
sizeClass	Class of the root element with size.	size	small medium large
variantClass	Class of the root element with variant.	variant	primary info warning danger
disabledClass	Class of the root element when disabled.	disabled
indeterminateClass	Class of the root element when indeterminate.	indeterminate
inputClass	Class of the native input element.
labelClass	Class of the label element.

Sass variables

Current theme ➜ Oruga

SASS Variable	Default
$checkbox-active-background-color	var(--#{$prefix}primary)
$checkbox-background-color	var(--#{$prefix}primary)
$checkbox-box-shadow	$control-box-shadow
$checkbox-border-color	var(--#{$prefix}primary)
$checkbox-border-style	solid
$checkbox-border-radius	var(--#{$prefix}base-border-radius)
$checkbox-border-width	2px
$checkbox-checked-box-shadow-length	0 0 0.5em
$checkbox-checked-box-shadow-opacity	0.8
$checkbox-checkmark-color	$primary-invert
$checkbox-disabled-opacity	var(--#{$prefix}base-disabled-opacity)
$checkbox-label-padding	0 0 0 0.5em
$checkbox-margin-sibiling	0.5em
$checkbox-size	1rem
$checkbox-line-height	1.5

See ➜ 📄 Full scss file

Current theme ➜ Bulma

SASS Variable	Default
$checkbox-size	1.25em
$checkbox-background-color	transparent
$checkbox-border-width	2px
$checkbox-colors	dv.$colors
$checkbox-border-color	css.getVar("grey")
$checkbox-border-radius	css.getVar("radius")
$checkbox-checkmark-color	css.getVar("primary-invert")
$checkbox-focus-color	hsl(from css.getVar("grey") h s l / 80%)
$checkbox-active-focus-color	hsl( from css.getVar("checkbox-active-background-color") h s l / 80%)
$checkbox-active-background-color	css.getVar("primary")
$checkbox-shadow	css.getVar("shadow")

See ➜ 📄 Full scss file

Current theme ➜ Bootstrap

The theme does not have any custom variables for this component.