import { OntarioCheckboxes } from '@ongov/ontario-design-system-component-library-react';
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
# ontario-checkboxes
Use checkboxes when you want the user to select one or more options from a list.
## User guidance
Please refer to the [Ontario Design System](https://designsystem.ontario.ca/components/detail/checkboxes.html) for current documentation guidance.
### Disabled and read-only states
This component intentionally does not provide group-level `readOnly` or `disabled` props.
Disabling form controls can create accessibility and usability barriers, and often does not explain what the user needs to fix.
Instead:
- keep controls and submission actions available
- use validation and error messaging to clearly identify missing or invalid input
For implementation examples, see [Error messaging](#error-messaging).
Source: https://designsystem.ontario.ca/components/detail/buttons.html#disabled-buttons
## Configuration
Once the component package has been installed (see Ontario Design System Component Library for installation instructions), the checkbox component can be added directly into the project's code, and can be customized by updating the properties outlined [here](#properties). Additional information on custom types for header properties are outlined [here](#custom-property-types). Please see the [examples](#examples) below for how to configure the component.
## Examples
Example of a bare-bones checkbox component, the legend for the checkbox fieldset is provided, as well as 2 checkbox options.
```mdx-code-block
```
```html
```
```mdx-code-block
```
```tsx
```
```mdx-code-block
```
```html
```
```mdx-code-block
```
Example of a checkbox component with multiple options, a hint text and hint expander for the entire checkbox group, and a hint expander on an individual option. It also has the `required` property set.
```mdx-code-block
```
```html
```
```mdx-code-block
```
```tsx
```
```mdx-code-block
```
```html
```
```mdx-code-block
```
In the following example, the selected checkbox options are set using the
component's `value`. Listen for the component `change` event to read the
current selected values.
```mdx-code-block
```
```html
```
```mdx-code-block
```
```tsx
{
console.log((event.target as HTMLOntarioCheckboxesElement).value);
console.log(event.detail.value);
}}
/>
```
```mdx-code-block
```
```html
```
```ts
handleCheckboxChange(event: Event) {
console.log((event.target as HTMLOntarioCheckboxesElement).value);
console.log((event as CustomEvent<{ value: string[] }>).detail.value);
}
```
```mdx-code-block
```
### Forms
The `ontario-checkboxes` supports integration with native HTML `
```
Remember to set the `name` attribute as this is used to identify the field when submitting the form.
## Event model
For most integrations, prefer the component `change` event and read the
selected values from `event.target.value`. That event also includes
`event.detail.value` as a convenience. Use `checkboxOnChange` when you
specifically want the component's per-option custom event payload.
Each custom event emitted by the component uses the
[`CustomEvent`](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent)
type. To access the data emitted by the component within the `CustomEvent` type
use the [CustomEvent.detail](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent/detail)
property.
Example of the component `change` event:
```html
```
Example `checkboxOnChange` usage when you need per-option detail:
```html
```
If the first checkbox is checked within `checkboxes-1`, the value of `event.detail` is the object emitted along with the `checkboxOnChange` event.
```js
{ checked: true, id: "checkbox-1", value: "checkbox-option-1" }
```
See the [Events](#events) table to learn more about the available custom events from the component and what the type of `CustomEvent.detail` will be.
### Native `change` events
The component uses a ShadowDOM to maintain encapsulation, however, this changes how the events flow from the inside of the component to the outside in the DOM.
The component keeps its `value` in sync with the currently selected checkbox
options.
The native `change` event hits the ShadowDOM boundary and stops propagating.
The implication of this is that it can't be listened for outside the
component. To attempt to overcome this, a synthetic change event is generated
and emitted. The original `change` event is available via the `detail`
property on the emitted event.
When using libraries that listen for events, this process may not work with them and a workaround might be required depending on the framework or library in use.
## Error messaging
Use validation and error messaging to help users understand what needs to be corrected.
### Setting an error message
Set `errorMessage` when required selection rules are not met, and keep options available for correction.
### Static vs live validation
Use a static `errorMessage` when validation happens on submit (for example, after a form post or submit handler check).
Use live validation when you want real-time feedback as users interact (for example, on change or blur).
For more guidance, visit the [Error messaging guidance page](https://designsystem.ontario.ca/components/detail/error-messaging.html).
```mdx-code-block
```
```html
```
```mdx-code-block
```
```tsx
```
```mdx-code-block
```
```html
```
```mdx-code-block
```
### Live validation
Keep the control available and validate selections on interaction (for example, on change, blur, or submit). When validation fails, set a contextual error message that explains how to fix the issue.
## Custom property types
### caption
The `caption` property is used to render the legend for the ontario-checkbox. It can be passed either a string or an object. If no `captionType` needs to be specified, it can be passed as a string.
```html
caption='{ "captionText": "Checkbox legend", "captionType": "large" }'
```
| Property name | Type | Description |
| ------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `captionText` | `string` | Text to display as the checkbox question |
| `captionType` | `"default" \| "large"\| "heading"` | The type of legend to display for the checkbox question. This is optional, and if no information is provided, it will default to the `default` type. |
### hintExpander
The `hintExpander` property is used to include the Hint Expander component underneath the checkbox legend. This is passed in as an object with key-value pairs. This is optional.
```html
hintExpander='{ "hint": "This is the hint expander title", "content": "This is the hint expander content - it is only
visible when the hint expander title (hint) is toggled" }'
```
| Property name | Type | Description |
| ------------- | -------- | --------------------------------------------------------------------------------------------------------------- |
| `hint` | `string` | Text to display as the hint expander label/title. When toggled, it will display/hide the `hintExpander` content |
| `content` | `string` | Text to display as the content of the hint expander |
### options
The options property will render out the different checkbox inputs and their labels. These are passed in as objects with key-value pairs, inside an array.
```html
options='[ { "value": "checkbox-option-1", "label": "Checkbox option 1 label", "elementId": "checkbox-1" }, { "value":
"checkbox-option-2", "label": "Checkbox option 2 label", "elementId": "checkbox-2", "hintExpander": { "hint": "Hint
expander for checkbox option 2", "content": "Example hint expander content for checkbox option 2" } }, ]'
```
| Property name | Type | Description |
| -------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value` | `string` | Text to defines the value associated with the input (this is also the value that is sent on submit) |
| `label` | `string` | Text to display as the label of the individual checkbox option |
| `elementId` | `string` | Text used to establish a relationship between checkbox option label and the checkbox option input. This ID must be unique to the checkbox option. |
| `hintExpander` | `hintExpander` | An optional hint expander to display for the individual checkbox option. Information on `hintExpander` properties can be found in the custom property above |
## Accessibility
- Do not preselect checkboxes (there should be no checked attribute by default on the checkbox)
- All checkboxes in a group should have the same name value to associate them as a group of options
## Technical Note: SSR (Server-Side Rendering) Considerations
The Ontario Checkboxes component supports server-side rendering, with a few considerations:
- **Language prop:** Language change events only fire in the browser after hydration. To ensure the correct language is rendered during SSR, pass the desired `language` explicitly as a prop.
- **Dynamic ID generation:** Each checkbox option should use a stable `elementId`. If option IDs are generated differently between server and client, hydration mismatches are more likely.
- **Hint text and accessibility IDs:** If using `ontario-hint-text`, note that the `aria-describedby` reference is resolved after hydration. Make sure this does not impact critical accessibility paths in your application.
- **Form participation:** This component uses the [Form-Associated Custom Elements](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals) API (`@AttachInternals`) to participate in native form submission. During SSR, it renders a checkbox-group structure that can support straightforward form submission when the group `name`, `language`, and option ids are stable. Group-level error messaging and emitted events become available after hydration.
- **Hydrated-only behaviour:** Group-level error messaging and custom event handling should be treated as hydrated behaviour. Keep the group `name` stable across all options and verify the full submit flow in the consuming application.
- **Framework guidance:** Use the HTML `