Checkboxes
`<gcds-checkboxes>`

Also called: checklist, check list.

Checkboxes provide a set of options for multiple responses.

GitHub
Figma

Checkboxes component preview

Coding and accessibility for checkboxes

Apply required attributes

Always use the following required attributes with gcds-checkboxes:

name
options

Use the `options` attribute

The options attribute uses an array of objects to render each checkbox.
Within each object in the options array, always use the object’s required properties:
- id
- label
The rest of the properties are optional.

Example:

{
  'id'!: '',
  'label'!: '',
  'value'?: '',
  'checked'?: '',
  'hint'?: '',
}

Set attributes based on number of checkboxes

Single checkbox

Add a single object in the options attribute to render a single checkbox.
Fieldset is removed from a single checkbox.

Group of checkboxes

Add more than one object in the options attribute to render multiple checkboxes.
Use the legend attribute to render the fieldset.

Use the `value` attribute

The value attribute provides a quick reference to the values checked inside the gcds-checkboxes component.
value is formatted as an array of strings.

Example:

[“checkboxOneValue”, checkboxTwoValue”]

Add hint text

Use the hint attribute to add hint text.

Hide the legend or labels

Visually hide the legend or label, while maintaining it for assistive technologies.
- Set the hide-legend attribute to true to visually hide the legend for checkbox groups.
- Set the hide-label attribute to true to visually hide the label for a single checkbox.
Avoid adding hint text if the legend and/or labels are hidden.

Add validation and error messages

Use the required attribute to activate the built-in error messages and validation for checkboxes.
Fields with specific input requirements will validate if the entry is invalid, even if it is not required.
For optional fields that need validation, like email address formats, add custom validation with a custom error message.

Examples

Explore the different ways you can configure the component. Each example shows a working implementation and ready-to-copy code.

Optional attributes

These attributes allow you to customize or extend the component’s behaviour and presentation.

`legend`

The legend attribute defines the legend for a group of checkboxes.

<gcds-checkboxes
legend="Legend"
name="checkexample"
options='[
  {"id": "form-check-1", "label": "Label", "hint": "Description or example to make the option clearer.", "value": "check1"},
  {"id": "form-check-2", "label": "Label", "hint": "Description or example to make the option clearer.", "value": "check2"}
]'>
</gcds-checkboxes>

`name`

The name attribute identifies the checkboxes component within a form. It is used to reference the component after a form is submitted.

<gcds-checkboxes
legend="Legend"
name="checkexample"
options='[
  {"id": "form-check-1", "label": "Label", "hint": "Description or example to make the option clearer.", "value": "check1"},
  {"id": "form-check-2", "label": "Label", "hint": "Description or example to make the option clearer.", "value": "check2"}
]'>
</gcds-checkboxes>

`options`

The options attribute defines the checkboxes to render by taking an array of objects, one per checkbox.

<gcds-checkboxes
legend="Legend"
name="checkexample"
options='[
  {"id": "form-check-1", "label": "Label", "hint": "Description or example to make the option clearer.", "value": "check1"},
  {"id": "form-check-2", "label": "Label", "hint": "Description or example to make the option clearer.", "value": "check2"}
]'>
</gcds-checkboxes>

Optional attributes

These attributes allow you to customize or extend the component’s behaviour and presentation.

`autofocus`

The autofocus attribute controls whether the first checkbox will be focused automatically when the page loads. By default, it is set to false. When set to true, the checkbox is focused on render.

<gcds-checkboxes
autofocus
legend="Legend"
name="checkexample"
options='[
  {"id": "form-check-1", "label": "Label", "hint": "Description or example to make the option clearer.", "value": "check1"},
  {"id": "form-check-2", "label": "Label", "hint": "Description or example to make the option clearer.", "value": "check2"}
]'>
</gcds-checkboxes>

`disabled`

The disabled attribute controls whether the checkboxes are disabled or not. By default, it is set to false.

<gcds-checkboxes
disabled legend="Legend"
name="checkexample"
options='[
  {"id": "form-check-1", "label": "Label", "hint": "Description or example to make the option clearer.", "value": "check1"},
  {"id": "form-check-2", "label": "Label", "hint": "Description or example to make the option clearer.", "value": "check2"}
]'>
</gcds-checkboxes>

`error-message`

The error-message attribute defines the error message to display for invalid checkboxes.

<gcds-checkboxes
error-message="Error message"
legend="Legend" name="checkexample"
options='[
  {"id": "form-check-1", "label": "Label", "hint": "Description or example to make the option clearer.", "value": "check1"},
  {"id": "form-check-2", "label": "Label", "hint": "Description or example to make the option clearer.", "value": "check2"}
]'>
</gcds-checkboxes>

`form`

The form attribute specifies the ID of the form that the checkboxes belong to.

<gcds-checkboxes
form="form-id"
legend="Legend"
name="checkexample"
options='[
  {"id": "form-check-1", "label": "Label", "hint": "Description or example to make the option clearer.", "value": "check1"},
  {"id": "form-check-2", "label": "Label", "hint": "Description or example to make the option clearer.", "value": "check2"}
]'>
</gcds-checkboxes>

`hide-label`

The hide-label attribute controls whether the label is hidden or not.

<gcds-checkboxes
hide-label name="checkbox"
options='[
  { "label": "Label for checkbox 1", "id": "checkbox1", "value": "checkbox1"}
]'>
</gcds-checkboxes>

`hide-legend`

The hide-legend attribute controls whether the legend is hidden or not.

<gcds-checkboxes
hide-legend legend="Legend"
name="checkexample"
options='[
  {"id": "form-check-1", "label": "Label", "hint": "Description or example to make the option clearer.", "value": "check1"},
  {"id": "form-check-2", "label": "Label", "hint": "Description or example to make the option clearer.", "value": "check2"}
]'>
</gcds-checkboxes>

`hint`

The hint attribute defines the hint text displayed under the label or legend.

<gcds-checkboxes
hint="Hint / Example message."
legend="Legend" name="checkexample"
options='[
  {"id": "form-check-1", "label": "Label", "hint": "Description or example to make the option clearer.", "value": "check1"},
  {"id": "form-check-2", "label": "Label", "hint": "Description or example to make the option clearer.", "value": "check2"}
]'>
</gcds-checkboxes>

`required`

The required attribute controls whether the checkbox fieldset is required or not. When set to true, it adds “required” after the label or legend, and activates the required validator.

<gcds-checkboxes
required legend="Legend"
name="checkexample"
options='[
  {"id": "form-check-1", "label": "Label", "hint": "Description or example to make the option clearer.", "value": "check1"},
  {"id": "form-check-2", "label": "Label", "hint": "Description or example to make the option clearer.", "value": "check2"}
]'>
</gcds-checkboxes>

`validate-on`

The validate-on attribute defines the validation event for the checkboxes.

<gcds-checkboxes
validate-on="other"
required legend="Legend"
name="checkexample"
options='[
  {"id": "form-check-1", "label": "Label", "hint": "Description or example to make the option clearer.", "value": "check1"},
  {"id": "form-check-2", "label": "Label", "hint": "Description or example to make the option clearer.", "value": "check2"}
]'>
</gcds-checkboxes>

`value`

The value attribute contains an array of the values of all currently checked checkboxes. It updates as selections change.

<gcds-checkboxes
  value='["check2"]'
  legend="Legend"
  name="checkexample"
  options='[
    {"id": "form-check-1", "label": "Label", "hint": "Description or example to make the option clearer.", "value": "check1"},
    {"id": "form-check-2", "label": "Label", "hint": "Description or example to make the option clearer.", "value": "check2"}
  ]'>
</gcds-checkboxes>

Code builder

Generate an instance of the component you need by selecting its code properties.

Explore by choosing different code values to generate the instance you want.
Get the code and pull it into your environment.
Add any copy you need to the component (like text for a label).

Note: The code builder uses English for all code elements, which follows standard practice.

Help us improve

Have questions or a request? Give feedback on our contact form.

Something's wrong? Raise it through GitHub with an account. You'll have access to the team's direct responses, progress made on your issue, and issues raised by others.

Give feedback

Report an issue on GitHub

2026-06-10

Checkboxes<gcds-checkboxes>

Checkboxes component preview

On this page

Coding and accessibility for checkboxes

Apply required attributes

Use the options attribute

Set attributes based on number of checkboxes

Single checkbox

Group of checkboxes

Use the value attribute

Add hint text

Hide the legend or labels

Examples

In this section

Optional attributes

legend

name

options

Optional attributes

autofocus

disabled

error-message

form

hide-label

hide-legend

hint

required

validate-on

value

Checkboxes
`<gcds-checkboxes>`

Use the `options` attribute

Use the `value` attribute

`legend`

`name`

`options`

`autofocus`

`disabled`

`error-message`

`form`

`hide-label`

`hide-legend`

`hint`

`required`

`validate-on`

`value`