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.
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', }),];{ "$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.
| prop | type | description |
|---|---|---|
options | array | Required. The options to check: values, { label, value } or any objects |
direction | row | column | Layout direction for the checkboxes. Defaults to column |
hint | string | Description text displayed below the label |
labelField | string | Custom key to use for the display label of each option. Defaults to label |
valueField | string | Custom key to use for the underlying value of each option. Defaults to value |
Use the property hint to provide instructions for the user.
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', }),];{ "$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" } ] } } ]}Custom Fields
Section titled “Custom Fields”You can map different fields for the options using labelField and valueField. The value holds the valueField of each checked option.
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', }),];{ "$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" } } ]}Direction
Section titled “Direction”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.
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'], }),];{ "$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" } } ]}Validation
Section titled “Validation”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.
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', }, }, }),];{ "$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" } } } ]}Styling
Section titled “Styling”Checkbox Groups can be styled as explained in the Styling Guide.
CSS Variables
Section titled “CSS Variables”The checkboxes share their tokens with the Checkbox, so one setting styles both.
| CSS Variable | Description |
|---|---|
--gui-checkbox-size | Width and height of each box. Defaults to 1rem |
--gui-checkbox-radius | Border radius of each box. Defaults to --gui-radius-sm |
--gui-checkbox-bg | Background of each box. Defaults to --gui-bg-surface |
--gui-checkbox-border | Border color of each box. Defaults to --gui-border-strong |
--gui-checkbox-tick | Color of a checked box and its tick. Defaults to --gui-intent-primary |
--gui-checkbox-gap | Space between each box and its text. Defaults to --gui-space-2 |
Anatomy
Section titled “Anatomy”This is the anatomy of the Checkbox Group Widget in case you want to use your CSS styles.
<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>