Components

CheckboxGroupField

Form field component for selecting multiple options using a group of checkboxes.

Component

View code

Show playground

Label (optional)

Option 1

Option 2

Option 3

Select one or more options.

Props

Props	Required	Default	Type
`label`	—	—	`string`
`options`	`true`	—	`CheckboxOption[]`
`modelValue`	`true`	—	`(string \| number \| boolean)[]`
`validator`	—	`null`	`(value: unknown) => string \| null`
`error`	—	`''`	`string`
`required`	—	`false`	`boolean`
`showOptionalLabel`	—	`true`	`boolean`
`optionalLabel`	—	—	`string`
`disabled`	—	`false`	`boolean`
`helpText`	—	—	`string`
`inverse`	—	`false`	`boolean`
`size`	—	`ControlFieldSize.MD`	`ControlFieldSize`
`helpTextPosition`	—	`Position.BOTTOM`	`Position`
`orientation`	—	`'vertical'`	`Orientation`
`layout`	—	`ListLayout.LIST`	`ListLayout`
`gridCols`	—	`3`	`number`
`gridTabletCols`	—	`2`	`number`
`gridMobileCols`	—	`1`	`number`
`gridGapClass`	—	`'gap-4'`	`string`
`listClass`	—	—	`string`
`showDivider`	—	`false`	`boolean`

Usage

label

Sets the label of the field group.

 <template>
    <CheckboxGroupField label="Choose options" />
</template>

Type: string

options

Sets the options for the checkboxes.

 <template>
    <CheckboxGroupField :options="exampleOptions" />
</template>
<script setup lang="ts">
const exampleOptions: CheckboxOption[] = [
    { id: 'option1', value: 'option1', label: 'Option 1' },
    { id: 'option2', value: 'option2', label: 'Option 2' },
    { id: 'option3', value: 'option3', label: 'Option 3' },
]
</script>

Type: CheckboxOption[]
Required: true

TypeScript interface

 interface CheckboxOption {
    id: string | number
    value: string | number | boolean
    label?: string
    ariaLabel?: string
    helpText?: string
    disabled?: boolean
}

Accessibility

If an option hides its visual label (for example, `label: ''`), provide `ariaLabel` so screen readers still announce an accessible name.

modelValue

Sets the array of currently selected values.

 <template>
    <CheckboxGroupField
        v-model="selectedValues"
        :options="exampleOptions"
    />
</template>
<script setup lang="ts">
const selectedValues = ref<(string | number | boolean)[]>([])
const exampleOptions: CheckboxOption[] = [
    { id: 'option1', value: 'option1', label: 'Option 1' },
    { id: 'option2', value: 'option2', label: 'Option 2' },
    { id: 'option3', value: 'option3', label: 'Option 3' },
]
</script>

Type: (string | number | boolean)[]
Required: true

validator

Sets the validator function for the field, which controls its internal validation state.

It can use the following validation utilities:

validateField
validateBooleanField

 <template>
    <CheckboxGroupField :validator="validateField" />
</template>

Type: function
Default: null

error (v-model:error)

Sets the error message of the field. This prop is bindable via v-model:error, allowing two-way syncing of the validation state.

 <template>
    <CheckboxGroupField v-model:error="errorMessage" />
</template>

Type: string
Default: ''

required

Sets whether the field is required.

 <template>
    <CheckboxGroupField required />
</template>

Type: boolean
Default: false

showOptionalLabel

When the field is not required, shows an "(optional)" hint next to the label. Set to false to hide it. The hint text defaults to a global setting that can be overridden project-wide, and can also be overridden per field with the optionalLabel prop.

 <template>
    <CheckboxGroupField label="Interests" :showOptionalLabel="false" />
</template>

Type: boolean
Default: true

optionalLabel

Overrides the "(optional)" hint text for this specific field, taking priority over the global default.

 <template>
    <CheckboxGroupField label="Interests" optionalLabel="(not required)" />
</template>

Type: string

disabled

Sets whether the field is disabled.

Important

Each checkbox option can also be individually disabled by setting the `disabled` property on the option object. If the `disabled` prop is set on the `CheckboxGroupField`, it will override the individual option settings and disable all options.

 <template>
    <CheckboxGroupField disabled />
</template>

Type: boolean
Default: false

helpText

Sets the help text of the field.

 <template>
    <CheckboxGroupField helpText="This is some help text." />
</template>

Type: string

helpTextPosition

Sets the position of the help text relative to the field group.

 <template>
    <CheckboxGroupField helpTextPosition="top" helpText="Appears above the options" />
</template>

Type: Position
Default: Position.BOTTOM

Options

Value	Description
`TOP`	Help text is displayed above the options.
`BOTTOM`	Help text is displayed below the options.

inverse

Sets whether the checkbox is displayed on the right side of the text.

 <template>
    <CheckboxGroupField inverse />
</template>

Type: boolean
Default: false

size

Sets the size of the checkbox options in the group. It uses the ControlFieldSize enum.

 <template>
    <CheckboxGroupField :size="ControlFieldSize.LG" />
</template>

Type: ControlFieldSize
Default: ControlFieldSize.MD

Options

Value	Description
`XS`	Extra Small
`SM`	Small
`MD`	Medium
`LG`	Large

orientation

Sets the orientation of the checkboxes. When layout is list, vertical stacks items in a column and horizontal wraps them in a row.

 <template>
    <CheckboxGroupField orientation="Orientation.HORIZONTAL" />
</template>

Type: Orientation
Default: Orientation.VERTICAL

Options

Value	Description
`VERTICAL`	Checkbox options are stacked vertically.
`HORIZONTAL`	Checkbox options are wrapped horizontally (list layout) or placed in a grid (grid layout).

layout

Sets the layout mode for the options container.

 <template>
    <CheckboxGroupField layout="ListLayout.GRID" :gridCols="3" :gridTabletCols="2" :gridMobileCols="1" />
</template>

Type: ListLayout
Default: ListLayout.LIST

Options

Value	Description
`LIST`	Options are arranged with flexbox, vertically stacked or horizontally wrapped depending on the orientation prop.
`GRID`	Options are arranged in a CSS grid using the cols, tabletCols, and mobileCols props.

gridCols

Sets the number of grid columns on desktop. Only applies when layout is ListLayout.GRID.

 <template>
    <CheckboxGroupField layout="grid" :gridCols="4" />
</template>

Type: number
Default: 3

gridTabletCols

Sets the number of grid columns on tablet. Only applies when layout is ListLayout.GRID.

 <template>
    <CheckboxGroupField layout="grid" :gridTabletCols="2" />
</template>

Type: number
Default: 2

gridMobileCols

Sets the number of grid columns on mobile. Only applies when layout is ListLayout.GRID.

 <template>
    <CheckboxGroupField layout="grid" :gridMobileCols="1" />
</template>

Type: number
Default: 1

gridGapClass

Sets the Tailwind gap utility passed to the grid container. Only applies when layout is ListLayout.GRID.

 <template>
    <CheckboxGroupField layout="grid" gridGapClass="gap-8" />
</template>

Type: string
Default: 'gap-4'

listClass

Appends extra classes to the list container. Only applies when layout is ListLayout.LIST. Useful for overriding spacing or adding custom layout utilities.

 <template>
    <CheckboxGroupField listClass="mt-2 px-4" />
</template>

Type: string

showDivider

Shows a divider line between consecutive options. Only applies when layout is ListLayout.LIST.

 <template>
    <CheckboxGroupField showDivider />
</template>

Type: boolean
Default: false