# auro-checkbox-group
The `auro-checkbox-group` element is a wrapper for `auro-checkbox` elements..
## Properties
| Property | Attribute | Type | Default | Description |
|---------------------------------|---------------------------------|--------------------------|-------------|--------------------------------------------------|
| [appearance](#appearance) | `appearance` | `'default' \| 'inverse'` | "'default'" | Defines whether the component will be on lighter or darker backgrounds. |
| [disabled](#disabled) | `disabled` | `boolean` | | If set, disables the checkbox group. |
| [error](#error) | `error` | `string` | | When defined, sets persistent validity to `customError` and sets the validation message to the attribute value. |
| [horizontal](#horizontal) | `horizontal` | `boolean` | | If set, checkboxes will be aligned horizontally. |
| [noValidate](#noValidate) | `noValidate` | `boolean` | | If set, disables auto-validation on blur. |
| [onDark](#onDark) | `onDark` | `boolean` | | DEPRECATED - use `appearance="inverse"` instead. |
| [required](#required) | `required` | `boolean` | | Populates the `required` attribute on the element. Used for client-side validation. |
| [setCustomValidity](#setCustomValidity) | `setCustomValidity` | `string` | | Sets a custom help text message to display for all validityStates. |
| [setCustomValidityCustomError](#setCustomValidityCustomError) | `setCustomValidityCustomError` | `string` | | Custom help text message to display when validity = `customError`. |
| [setCustomValidityValueMissing](#setCustomValidityValueMissing) | `setCustomValidityValueMissing` | `string` | | Custom help text message to display when validity = `valueMissing`. |
| [validity](#validity) | `validity` | `string` | | Specifies the `validityState` this element is in. |
## Methods
| Method | Type | Description |
|------------|----------------------------------------|--------------------------------------------------|
| [reset](#reset) | `(): void` | Resets component to initial state. |
| [validate](#validate) | `(force?: boolean \| undefined): void` | Validates value.
**force**: Whether to force validation. |
## Events
| Event | Type | Description |
|-----------------------------|--------------------|--------------------------------------------------|
| `auroFormElement-validated` | | Notifies that the `validity` and `errorMessage` values have changed. |
| [input](#input) | `CustomEvent` | |
## Slots
| Name | Description |
|-----------------|--------------------------------------------------|
| [default](#default) | The default slot for the checkbox items. |
| [helpText](#helpText) | Allows for the helper text to be overridden. |
| [legend](#legend) | Allows for the legend to be overridden. |
| [optionalLabel](#optionalLabel) | Allows overriding the optional display text "(optional)", which appears next to the label. |
# auro-checkbox
The `auro-checkbox` element is for the purpose of allowing users to select one or more options of a limited number of choices.
## Properties
| Property | Attribute | Type | Default | Description |
|--------------|--------------|--------------------------|-------------|--------------------------------------------------|
| [appearance](#appearance) | `appearance` | `'default' \| 'inverse'` | "'default'" | Defines whether the component will be on lighter or darker backgrounds. |
| [checked](#checked) | `checked` | `boolean` | | If set to true, the checkbox will be filled with a checkmark. |
| [disabled](#disabled) | `disabled` | `boolean` | | If set to true, the checkbox will not be clickable. |
| [error](#error) | `error` | `boolean` | | If set to true, the checkbox will be displayed with an error state. |
| [id](#id) | `id` | `string` | | The id global attribute defines an identifier (ID) which must be unique in the whole document. |
| [name](#name) | `name` | `string` | | Accepts any string and is used to identify related checkboxes when submitting form data. |
| [onDark](#onDark) | `onDark` | `boolean` | | DEPRECATED - use `appearance="inverse"` instead. |
| [value](#value) | `value` | `string` | | Sets the element's input value. Must be unique within an auro-checkbox-group element. |
## Methods
| Method | Type | Description |
|---------|------------|------------------------------------|
| [reset](#reset) | `(): void` | Resets component to initial state. |
## Events
| Event | Type | Description |
|-------------------------|--------------------|--------------------------------------------------|
| `auroCheckbox-focusin` | `CustomEvent` | |
| `auroCheckbox-focusout` | `CustomEvent` | |
| `auroCheckbox-input` | `CustomEvent` | |
| [change](#change) | `CustomEvent` | (Deprecated) Notifies when checked value is changed. |
| [input](#input) | `InputEvent` | Notifies when when checked value is changed by user's interface. |
## Slots
| Name | Description |
|-----------|------------------------------------------|
| [default](#default) | The default slot for the checkbox label. |
## CSS Shadow Parts
| Part | Description |
|------------------|-------------------------------------------|
| [checkbox](#checkbox) | apply css to a specific checkbox. |
| `checkbox-input` | apply css to a specific checkbox's input. |
| `checkbox-label` | apply css to a specific checkbox's label. |
## Basic
Form label goes here
Checkbox option
Checkbox option
Checkbox option that has some extra text that should wrap when rendered in a narrow container
Checkbox option
See code
```html
Form label goes here
Checkbox option
Checkbox option
Checkbox option that has some extra text that should wrap when rendered in a narrow container
Checkbox option
```
## Property & Attribute Examples
### Appearance on Dark Backgrounds
Use the `appearance="inverse"` attribute to render the checkbox for use on dark backgrounds.
Form label goes here
Checkbox option
Checkbox option
Checkbox option
Checkbox option
See code
Form label goes here
Checkbox option
Checkbox option
Checkbox option
Checkbox option
### Disabled
Use the `disabled` attribute to disable individual `` elements or the entire ``.
#### Disabled Checkbox within Group
The `disabled` attribute used to disable a single `` element.
Form label goes here
Checkbox option
Disabled checkbox option
Disabled checkbox option
Checkbox option
See code
```html
Form label goes here
Checkbox option
Disabled checkbox option
Disabled checkbox option
Checkbox option
```
#### Disabled Group
The `disabled` attribute used to disable the entire ``.
Form label goes here
Disabled checkbox option
Disabled checkbox option
Disabled checkbox option
Disabled checkbox option
Form label goes here
Disabled checkbox option
Disabled checkbox option
Disabled checkbox option
Disabled checkbox option
See code
```html
Form label goes here
Disabled checkbox option
Disabled checkbox option
Disabled checkbox option
Disabled checkbox option
```
Form label goes here
Disabled checkbox option
Disabled checkbox option
Disabled checkbox option
Disabled checkbox option
### Horizontal Group
Using the `horizontal` attribute will render the checkbox options on a horizontal line.
**Note**: Using the `horizontal` attribute has a limit of 3 options. Beyond three, options will be listed in vertically.
Form label goes here
Yes
No
Maybe
See code
```html
Form label goes here
Yes
No
Maybe
```
### Form Validation
In the `auro-checkbox-group` element, the `required` and `error` states are the two possible validation states.
It should be noted that form validation is only supported within an `auro-checkbox-group` element. In order to support validation on a single `auro-checkbox` element, it must be wrapped in an `auro-checkbox-group`.
### Error
Use the `error` attribute to force an error state on the element.
The `error` attribute used to set error state on the entire ``. If using the `error` attribute on an ``, a string with the error message needs to be passed along with the attribute.
**Note**: The `error` attribute is only supported on the `` element, not on individual `` elements.
Form label goes here
Error checkbox option
Error checkbox option
Error checkbox option
Error checkbox option
Form label goes here
Error checkbox option
Error checkbox option
Error checkbox option
Error checkbox option
See code
```html
Form label goes here
Error checkbox option
Error checkbox option
Error checkbox option
Error checkbox option
```
Form label goes here
Error checkbox option
Error checkbox option
Error checkbox option
Error checkbox option
#### Required
When present, the `required` attribute specifies that at least one or more `` elements within the `` must be checked.
Form label goes here
Checkbox option
Checkbox option
Checkbox option
Checkbox option
See code
```html
Form label goes here
Checkbox option
Checkbox option
Checkbox option
Checkbox option
```
## Slot Examples
### Custom Optional Label
The `` supports an `optionalLabel` slot, where users can can override the default `(optional)` notification text.
Form label goes here
- optional
Checkbox option
Checkbox option
Checkbox option that has some extra text that should wrap when rendered in a narrow container
Checkbox option
See code
```html
Form label goes here
- optional
Checkbox option
Checkbox option
Checkbox option that has some extra text that should wrap when rendered in a narrow container
Checkbox option
```
## Common Usage Patterns & Functional Examples
### Reset State
Use the `reset()` method to reset the ``'s `value` and `validity` state. Doing so will preserve all other attributes and properties.
Reset
Form label goes here
Checkbox option
Checkbox option
Checkbox option
Checkbox option
See code
```html
Reset
Form label goes here
Checkbox option
Checkbox option
Checkbox option
Checkbox option
```
```js
export function resetStateExample() {
const elem = document.querySelector('#resetStateExample');
document.querySelector('#resetStateBtn').addEventListener('click', () => {
elem.reset();
});
}
```
## Restyle Component with CSS Variables
The component may be restyled by changing the values of the following token(s).
```scss
@use "@aurodesignsystem/design-tokens/dist/themes/alaska/SCSSVariables--alaska" as v;
:host {
--ds-auro-checkbox-border-color: var(--ds-basic-color-border-bold, #{v.$ds-basic-color-border-bold});
--ds-auro-checkbox-checkmark-color: var(--ds-advanced-color-boolean-indicator, #{v.$ds-advanced-color-boolean-indicator});
--ds-auro-checkbox-container-color: var(--ds-advanced-color-boolean-isfalse, #{v.$ds-advanced-color-boolean-isfalse});
--ds-auro-checkbox-label-color: var(--ds-basic-color-texticon-default, #{v.$ds-basic-color-texticon-default});
--ds-auro-checkbox-outline-color: transparent;
--ds-auro-checkbox-group-text-color: var(--ds-basic-color-texticon-default, #{v.$ds-basic-color-texticon-default});
}
```