Appearance

Light vs. Dark Background

The appearance attribute defines whether the component renders on lighter or darker backgrounds. Supported values are default and inverse. The default value is default.

Form label goes here

Checkbox option

Checkbox option that has some extra text that should wrap when rendered in a narrow container

Checkbox option

See code

<auro-checkbox-group>
  <span slot="legend">Form label goes here</span>
  <auro-checkbox value="value1" name="basic" id="checkbox-basic1">Checkbox option</auro-checkbox>
  <auro-checkbox value="value2" name="basic" id="checkbox-basic2">Checkbox option</auro-checkbox>
  <auro-checkbox value="value3" name="basic" id="checkbox-basic3">Checkbox option that has some extra text that should wrap when rendered in a narrow container</auro-checkbox>
  <auro-checkbox value="value4" name="basic" id="checkbox-basic4">Checkbox option</auro-checkbox>
</auro-checkbox-group>

Form label goes here

Checkbox option

See code

<auro-checkbox-group appearance="inverse">
  <span slot="legend">Form label goes here</span>
  <auro-checkbox value="value1" name="basic" id="checkbox-basic1">Checkbox option</auro-checkbox>
  <auro-checkbox value="value2" name="basic" id="checkbox-basic2" checked>Checkbox option</auro-checkbox>
  <auro-checkbox value="value3" name="basic" id="checkbox-basic3">Checkbox option</auro-checkbox>
  <auro-checkbox value="value4" name="basic" id="checkbox-basic4">Checkbox option</auro-checkbox>
</auro-checkbox-group>

Horizontal Layout

Using the horizontal attribute will render the checkbox options on a horizontal line.

Note: The horizontal attribute has a limit of 3 options. Beyond three, options will be listed vertically.

Form label goes here

Yes

Maybe

See code

<auro-checkbox-group horizontal>
  <span slot="legend">Form label goes here</span>
  <auro-checkbox value="yes" name="horizontal" id="checkbox-horizontal1">Yes</auro-checkbox>
  <auro-checkbox value="no" name="horizontal" id="checkbox-horizontal2">No</auro-checkbox>
  <auro-checkbox value="maybe" name="horizontal" id="checkbox-horizontal3">Maybe</auro-checkbox>
</auro-checkbox-group>

Tokens

The component may be restyled by overriding the following CSS custom properties (design tokens).

@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});
}

Custom themed checkbox group

Checkbox option

See code

<style>
  #customTokensExample {
    --ds-auro-checkbox-border-color: purple;
    --ds-auro-checkbox-checkmark-color: white;
    --ds-auro-checkbox-container-color: lavender;
    --ds-auro-checkbox-label-color: purple;
    --ds-auro-checkbox-outline-color: mediumpurple;
    --ds-auro-checkbox-group-text-color: purple;
  }
</style>
<auro-checkbox-group id="customTokensExample">
  <span slot="legend">Custom themed checkbox group</span>
  <auro-checkbox value="value1" name="tokens" id="checkbox-tokens1">Checkbox option</auro-checkbox>
  <auro-checkbox value="value2" name="tokens" id="checkbox-tokens2" checked>Checkbox option</auro-checkbox>
  <auro-checkbox value="value3" name="tokens" id="checkbox-tokens3">Checkbox option</auro-checkbox>
</auro-checkbox-group>

CSS Shadow Parts

CSS Shadow Parts allow you to style elements inside a web component's shadow DOM using the ::part() pseudo-element. The following parts are exposed by <auro-checkbox>.

Part	Description
`checkbox`	The checkbox container element.
`checkbox-input`	The checkbox input element.
`checkbox-label`	The checkbox label element.

CSS Shadow Parts example

Styled checkbox

Default checkbox

See code

<style>
  #cssPartsExample::part(checkbox) {
    border: 2px solid mediumpurple;
    border-radius: 6px;
  }

  #cssPartsExample::part(checkbox-label) {
    font-style: italic;
    color: purple;
  }
</style>
<auro-checkbox-group>
  <span slot="legend">CSS Shadow Parts example</span>
  <auro-checkbox id="cssPartsExample" value="styled" name="parts" checked>Styled checkbox</auro-checkbox>
  <auro-checkbox value="default" name="parts" id="checkbox-parts2">Default checkbox</auro-checkbox>
</auro-checkbox-group>

Behavior

Disabled Checkbox

Use the disabled attribute to disable individual <auro-checkbox> elements.

Form label goes here

Checkbox option

Disabled checkbox option

Checkbox option

See code

<auro-checkbox-group>
  <span slot="legend">Form label goes here</span>
  <auro-checkbox value="disabled-value1" name="disabled-value1" id="checkbox-disabled1">Checkbox option</auro-checkbox>
  <auro-checkbox value="disabled-value2" name="disabled-value2" id="checkbox-disabled2" checked disabled>Disabled checkbox option</auro-checkbox>
  <auro-checkbox value="disabled-value3" name="disabled-value3" id="checkbox-disabled3" disabled>Disabled checkbox option</auro-checkbox>
  <auro-checkbox value="disabled-value4" name="disabled-value4" id="checkbox-disabled4" checked>Checkbox option</auro-checkbox>
</auro-checkbox-group>

Disabled Group

Use the disabled attribute on the <auro-checkbox-group> to disable all checkboxes in the group.

Form label goes here

Disabled checkbox option

See code

<auro-checkbox-group disabled>
  <span slot="legend">Form label goes here</span>
  <auro-checkbox value="disabled-value1" name="disabledGroup" id="checkbox-disabledGroup1">Disabled checkbox option</auro-checkbox>
  <auro-checkbox value="disabled-value2" name="disabledGroup" id="checkbox-disabledGroup2" checked>Disabled checkbox option</auro-checkbox>
  <auro-checkbox value="disabled-value3" name="disabledGroup" id="checkbox-disabledGroup3">Disabled checkbox option</auro-checkbox>
  <auro-checkbox value="disabled-value4" name="disabledGroup" id="checkbox-disabledGroup4">Disabled checkbox option</auro-checkbox>
</auro-checkbox-group>

Required

When present, the required attribute specifies that at least one <auro-checkbox> within the group must be checked.

Form label goes here

Checkbox option

See code

<auro-checkbox-group required setCustomValidityValueMissing="Please select an option">
  <span slot="legend">Form label goes here</span>
  <auro-checkbox value="value1" name="required" id="checkbox-required1">Checkbox option</auro-checkbox>
  <auro-checkbox value="value2" name="required" id="checkbox-required2">Checkbox option</auro-checkbox>
  <auro-checkbox value="value3" name="required" id="checkbox-required3">Checkbox option</auro-checkbox>
  <auro-checkbox value="value4" name="required" id="checkbox-required4">Checkbox option</auro-checkbox>
</auro-checkbox-group>

Error

Use the error attribute to force an error state on the <auro-checkbox-group>. Pass a string with the error message.

Note: The error attribute is only supported on the <auro-checkbox-group> element, not on individual checkboxes.

Form label goes here

Error checkbox option

See code

<auro-checkbox-group error="custom error">
  <span slot="legend">Form label goes here</span>
  <auro-checkbox value="error-value1" name="error" id="checkbox-errorGroup1">Error checkbox option</auro-checkbox>
  <auro-checkbox value="error-value2" name="error" id="checkbox-errorGroup2">Error checkbox option</auro-checkbox>
  <auro-checkbox value="error-value3" name="error" id="checkbox-errorGroup3">Error checkbox option</auro-checkbox>
  <auro-checkbox value="error-value4" name="error" id="checkbox-errorGroup4" checked>Error checkbox option</auro-checkbox>
</auro-checkbox-group>

No Validation

Use the noValidate attribute to disable auto-validation on blur. Validation can still be triggered programmatically via the validate() method.

No auto-validation on blur

Checkbox option

See code

<auro-checkbox-group required noValidate setCustomValidityValueMissing="Please select an option" id="noValidateExample">
  <span slot="legend">No auto-validation on blur</span>
  <auro-checkbox value="value1" name="noValidate" id="checkbox-noValidate1">Checkbox option</auro-checkbox>
  <auro-checkbox value="value2" name="noValidate" id="checkbox-noValidate2">Checkbox option</auro-checkbox>
  <auro-checkbox value="value3" name="noValidate" id="checkbox-noValidate3">Checkbox option</auro-checkbox>
</auro-checkbox-group>