Skip to content
Forms, switch product

Checkbox Group

Checkbox Group widgets are Input Fields that let the user check any number of options from a list. Their value is an array with the values of the checked options, in the order of the options, whatever order the user checks them in.

checkbox-group.ts
import { gui } from '@golemui/gui-shared';
export default [
gui.inputs.checkboxGroup('toppings', {
options: [
{
label: 'Cheese',
value: 'cheese',
},
{
label: 'Ham',
value: 'ham',
},
{
label: 'Olives',
value: 'olives',
},
{
label: 'Mushrooms',
value: 'mushrooms',
},
],
label: 'Toppings',
}),
];
checkbox-group.json
{
"$schema": "https://golemui.com/schemas/form.schema.json",
"form": [
{
"kind": "input",
"type": "checkboxGroup",
"path": "toppings",
"label": "Toppings",
"props": {
"options": [
{ "label": "Cheese", "value": "cheese" },
{ "label": "Ham", "value": "ham" },
{ "label": "Olives", "value": "olives" },
{ "label": "Mushrooms", "value": "mushrooms" }
]
}
}
]
}

To pick exactly one option, use a Radio Group. For a single yes or no, use a Checkbox. For a long list, a Multi Select List or a Multi Select Dropdown take less room.

Use these props to customize your Checkbox Group widget.

proptypedescription
optionsarrayRequired. The options to check: values, { label, value } or any objects
directionrow | columnLayout direction for the checkboxes. Defaults to column
hintstringDescription text displayed below the label
labelFieldstringCustom key to use for the display label of each option. Defaults to label
valueFieldstringCustom key to use for the underlying value of each option. Defaults to value

Use the property hint to provide instructions for the user.

checkbox-group.ts
import { gui } from '@golemui/gui-shared';
export default [
gui.inputs.checkboxGroup('toppings', {
hint: 'Pick as many as you like.',
options: [
{
label: 'Cheese',
value: 'cheese',
},
{
label: 'Ham',
value: 'ham',
},
{
label: 'Olives',
value: 'olives',
},
],
label: 'Toppings',
}),
];
checkbox-group.json
{
"$schema": "https://golemui.com/schemas/form.schema.json",
"form": [
{
"kind": "input",
"type": "checkboxGroup",
"path": "toppings",
"label": "Toppings",
"props": {
"hint": "Pick as many as you like.",
"options": [
{ "label": "Cheese", "value": "cheese" },
{ "label": "Ham", "value": "ham" },
{ "label": "Olives", "value": "olives" }
]
}
}
]
}

You can map different fields for the options using labelField and valueField. The value holds the valueField of each checked option.

checkbox-group.ts
import { gui } from '@golemui/gui-shared';
export default [
gui.inputs.checkboxGroup('channels', {
options: [
{
name: 'Email',
id: 'email',
},
{
name: 'SMS',
id: 'sms',
},
{
name: 'Push notification',
id: 'push',
},
],
labelField: 'name',
valueField: 'id',
label: 'Notify me by',
}),
];
checkbox-group.json
{
"$schema": "https://golemui.com/schemas/form.schema.json",
"form": [
{
"kind": "input",
"type": "checkboxGroup",
"path": "channels",
"label": "Notify me by",
"props": {
"options": [
{ "name": "Email", "id": "email" },
{ "name": "SMS", "id": "sms" },
{ "name": "Push notification", "id": "push" }
],
"labelField": "name",
"valueField": "id"
}
}
]
}

Use the direction property to lay the checkboxes out in a row. Options given as plain strings are both the label and the value, and defaultValue checks some of them from the start.

checkbox-group.ts
import { gui } from '@golemui/gui-shared';
export default [
gui.inputs.checkboxGroup('days', {
options: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri'],
direction: 'row',
label: 'Delivery days',
defaultValue: ['Mon', 'Wed'],
}),
];
checkbox-group.json
{
"$schema": "https://golemui.com/schemas/form.schema.json",
"form": [
{
"kind": "input",
"type": "checkboxGroup",
"path": "days",
"label": "Delivery days",
"defaultValue": ["Mon", "Wed"],
"props": {
"options": ["Mon", "Tue", "Wed", "Thu", "Fri"],
"direction": "row"
}
}
]
}

A Checkbox Group takes an array validator. required means at least one option is checked, and minItems and maxItems set how many the user can check. The user can always check another box: past maxItems the error says why the value is not valid.

An untouched group holds undefined, not an empty array, so word the empty group with both messages.required and messages.invalid.

checkbox-group.ts
import { gui } from '@golemui/gui-shared';
export default [
gui.inputs.checkboxGroup('extras', {
hint: 'Pick one or two.',
options: ['Napkins', 'Cutlery', 'Sauce'],
label: 'Extras',
validator: {
required: true,
maxItems: 2,
messages: {
invalid: 'Pick at least one extra',
required: 'Pick at least one extra',
maxItems: 'Pick at most two extras',
},
},
}),
];
checkbox-group.json
{
"$schema": "https://golemui.com/schemas/form.schema.json",
"form": [
{
"kind": "input",
"type": "checkboxGroup",
"path": "extras",
"label": "Extras",
"props": {
"hint": "Pick one or two.",
"options": ["Napkins", "Cutlery", "Sauce"]
},
"validator": {
"type": "array",
"required": true,
"maxItems": 2,
"messages": {
"invalid": "Pick at least one extra",
"required": "Pick at least one extra",
"maxItems": "Pick at most two extras"
}
}
}
]
}

Checkbox Groups can be styled as explained in the Styling Guide.

The checkboxes share their tokens with the Checkbox, so one setting styles both.

CSS VariableDescription
--gui-checkbox-sizeWidth and height of each box. Defaults to 1rem
--gui-checkbox-radiusBorder radius of each box. Defaults to --gui-radius-sm
--gui-checkbox-bgBackground of each box. Defaults to --gui-bg-surface
--gui-checkbox-borderBorder color of each box. Defaults to --gui-border-strong
--gui-checkbox-tickColor of a checked box and its tick. Defaults to --gui-intent-primary
--gui-checkbox-gapSpace between each box and its text. Defaults to --gui-space-2

This is the anatomy of the Checkbox Group Widget in case you want to use your CSS styles.

checkbox-group-anatomy.html
<gui-checkbox-group-input class="gui-checkbox-group gui-field">
<gui-checkbox-group class="gui-field">
<span class="gui-label" id="fieldUid_label">
<span class="gui-label__text">Label</span>
<div class="gui-widget-hint" id="fieldUid_hint" aria-hidden="true">Hint</div>
</span>
<div
role="group"
class="gui-widget"
id="fieldUid"
aria-labelledby="fieldUid_label"
aria-describedby="fieldUid_hint"
>
<label for="fieldUid_0">
<input
type="checkbox"
id="fieldUid_0"
form="fieldUid_none"
value="a"
aria-describedby="fieldUid_hint"
/>
Option A
</label>
<label for="fieldUid_1">
<input
type="checkbox"
id="fieldUid_1"
form="fieldUid_none"
value="b"
aria-describedby="fieldUid_hint"
/>
Option B
</label>
<label for="fieldUid_2">
<input
type="checkbox"
id="fieldUid_2"
form="fieldUid_none"
value="c"
aria-describedby="fieldUid_hint"
/>
Option C
</label>
</div>
<div class="gui-validator gui-validator--empty" id="fieldUid_errors" role="alert"></div>
</gui-checkbox-group>
</gui-checkbox-group-input>