CheckboxGroup

Basic Usage

Planets

Earth

Reach

Harvest

Ships

Pillar of Autumn

In Amber Clad

Forward Unto Dawn

<script setup>
import { CheckboxGroup, Checkbox } from '@8ctavio/vergil/components'
import { useModel } from '@8ctavio/vergil'
const planets = useModel([])
const ships = useModel([])

const planetOptions = {
    earth: 'Earth',
    reach: 'Reach',
    harvest: 'Harvest'
}
</script>

<template>
    <!-- options prop: Checkbox value-label pairs -->
    <CheckboxGroup v-model="planets" :options="planetOptions" label="Planets"/>

    <!-- default slot -->
    <CheckboxGroup v-model="ships" label="Ships">
        <Checkbox value="pillarOfAutumn" label="Pillar of Autumn" checked/>
        <Checkbox value="inAmberClad" label="In Amber Clad" theme="user"/>
        <Checkbox value="forwardUntoDawn" label="Forward Unto Dawn"/>
    </CheckboxGroup>
</template>

Props

Props that affect a Checkbox component's appereance are passed to (and, therefore, shared between) all underlying CheckboxGroup's Checkbox components.

Options

options: (string | [string, string])[] | Record<string, string | [string, string]> = []

The options prop is an array or (plain) object that provides the required data to define each option's value, label, and description, which correspond to the value, label, and description props of each underlying Checkbox components.

Options' values, labels, and descriptions can be automatically inferred from the values of options — each denoted as option — if they're either a string or an array of strings.

The following table summarizes how option's label and description are inferred from an option.

Type of option	label	description
string	option	undefined
string[]	option[0]	option[1]

The following table summarizes how an option's value is inferred depending on the type of options.

Type of options	value
Array	Same as label
object	The option's key

Example. Options Array

<script setup>
const options = [
    'Option 1',
    ['Option 2', 'Description 2']
]
</script>

<template>
    <CheckboxGroup v-model="checked" :options/>
</template>

Options array

Option 1

Option 2

Description 2

checked.value === ''

Example. Options Object

<script setup>
const options = {
    value1: 'Option 1',
    value2: ['Option 2', 'Description 2']
}
</script>

<template>
    <CheckboxGroup v-model="checked" :options/>
</template>

Options object

Option 1

Option 2

Description 2

checked.value === ''

TIP

The CheckboxGroup default slot may be used instead to directly pass Checkbox components. In such case, the options prop is ignored and CheckboxGroup group-level props may be overwritten on each Checkbox component.

Option's attributes

option-[value|label|description]: (string | Function)

The option-value, option-label, and option-description props allow to specify custom options' values, labels, and descriptions.

As strings, these props represent an object key. If an option is an object, the resulting value/label/description is obtained by accessing that object with the provided key.

<script setup>
const options = [{
    id: '123',
    name: 'Abc Def',
    email: 'abc.def@vergil.com'
},{
    id: '456',
    name: 'Uvw Xyz',
    email: 'uvw.xyz@vergil.com'
}]
</script>

<template>
    <CheckboxGroup v-model="checked" :options
        option-value="id"    
        option-label="name"
        option-description="email"
    />
</template>

Abc Def

abc.def@vergil.com

Uvw Xyz

uvw.xyz@vergil.com

checked.value === ''

As functions, these props are called for each option, receive the option and its key (index for arrays) as arguments, and their return value becomes the resulting value/label/description.

<script setup>
const options = [{
    id: '123',
    name: 'Abc Def',
    email: 'abc.def@vergil.com'
},{
    id: '456',
    name: 'Uvw Xyz',
    email: 'uvw.xyz@vergil.com'
}]
</script>

<template>
    <CheckboxGroup v-model="checked" :options
        :option-value="option => kebabCase(option.name)"    
        :option-label="option => option.name.split(' ')[0]"
        :option-description="option => `@@mail@@ ${option.email}`"
    />
</template>

Abc

mail abc.def@vergil.com

Uvw

mail uvw.xyz@vergil.com

checked.value === ''

The following functions are the default values for the option-value, option-label, and option-description props.

function defaultOptionValue(option, key) {
    return typeof key === 'number'
        ? Array.isArray(option) ? option[0] : option
        : key
}
function defaultOptionLabel(option) {
    return Array.isArray(option) ? option[0] : option
}
function defaultOptionDescription {
    return Array.isArray(option) ? option[1] : undefined
}

Options' attributes

options-attributes: Record<string, unknown> | ((...Args) => Record<string, unknown>)

As an object, options-attributes contains additional attributes to apply to all underlying Checkbox components.

<CheckboxGroup
    :options
    :options-attributes="{
        'data-custom': 'data'
    }"
/>

As a function, options-attributes is called for each option, receives the computed Checkbox component's key, value, label, and description, and its return object becomes the additional attributes.

<CheckboxGroup
    :options
    :options-attributes="(key,value,label,description) => ({
        /* additional attributes */
    })
/>

Variant

variant: ('classic' | 'card' | 'toggle' | 'list') = 'classic'

Classic

Label 1

Label 2

Label 3

Card

Label 1

Label 2

Label 3

List

Label 1

Label 2

Label 3

Toggle

Label 1

Label 2

Label 3

Show symbol

show-symbol: boolean

Card

Label 1

Label 2

Label 3

List

Label 1

Label 2

Label 3

Toggle

Label 1

Label 2

Label 3

Direction

direction: ('column' | 'row') = 'column'

Column

Label 1

Label 2

Row

Label 1

Label 2

Theme

theme: theme = 'brand'

Brand

Brand 1

Brand 2

User

User 1

User 2

Ok

Ok 1

Ok 2

Info

Info 1

Info 2

Warn

Warn 1

Warn 2

Danger

Danger 1

Danger 2

Neutral

Neutral 1

Neutral 2

Size

size: ('xs' | 'sm' | 'md' | 'lg' | 'xl') = 'md'

Extra Small

Extra Small 1

Extra Small 2

Small

Small 1

Small 2

Medium

Medium 1

Medium 2

Large

Large 1

Large 2

Extra Large

Extra Large 1

Extra Large 2

Radius

radius: ('none' | 'sm' | 'md' | 'lg' | 'full') = 'full'

None

None 1

None 2

Small

Small 1

Small 2

Medium

Medium 1

Medium 2

Large

Large 1

Large 2

Full

Full 1

Full 2

Spacing

spacing: ('compact' | 'expanded') = ''

XS Compact

XS Compact 1

XS Compact 2

XS Default

XS Default 1

XS Default 2

XS Expanded

XS Expanded 1

XS Expanded 2

SM Compact

SM Compact 1

SM Compact 2

SM Default

SM Default 1

SM Default 2

SM Expanded

SM Expanded 1

SM Expanded 2

MD Compact

MD Compact 1

MD Compact 2

MD Default

MD Default 1

MD Default 2

MD Expanded

MD Expanded 1

MD Expanded 2

LG Compact

LG Compact 1

LG Compact 2

LG Default

LG Default 1

LG Default 2

LG Expanded

LG Expanded 1

LG Expanded 2

XL Compact

XL Compact 1

XL Compact 2

XL Default

XL Default 1

XL Default 2

XL Expanded

XL Expanded 1

XL Expanded 2

Disabled

disabled: boolean

Disabled

Disabled 1

Disabled 2

Elements

element	tag	description
options	<div.toggle-group-wrapper>	Wrapper of underlying Checkbox components.

Anatomy

<div.form-field.checkbox-group/>

<div.form-field-label-wrapper/>

<label.form-field-label/>

<span.form-field-hint/>

<p.form-field-details.form-field-description/>

<div.toggle-group-wrapper/>

<slot name="default"/>

<Checkbox v-for="(text,value) in options"/>

<p.form-field-details.form-field-help/>

API Reference

Props

prop	type	default
value	array | string	[]
options	(string | [string, string])[] | Record<string, string | [string, string]>	[]
optionValue	string | ((option: unknown, key: string | number) => string)
optionLabel	string | ((option: unknown, key: string | number) => string)
optionDescription	string | ((option: unknown, key: string | number) => string)
optionsAttributes	Record<string, unknown> | ((key: string | number, value: string, label: string, description: string) => Record<string, unknown>)
variant	'classic' | 'card' | 'list' | 'toggle'	'classic'
showSymbol	boolean
direction	'column' | 'row'	'column'
disabled	boolean
label	string
hint	string
description	string
help	string
showErrros	boolean
descendant	boolean
theme	'brand' | 'user' | 'ok' | 'info' | 'warn' | 'danger' | 'neutral'	'brand'
size	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'
radius	'none' | 'sm' | 'md' | 'lg' | 'full'	'md'
spacing	'' | 'compact' | 'extended'	''
validator	Function
eagerValidation	boolean
elements	object

Configuration options

The CheckboxGroup is configured through the Checkbox configuration options.