Checkbox Group

A set of checkable buttons where multiple options can be selected at a time.

Usage

To display a checkbox group, list two or more CheckboxGroupItem components within CheckboxGroup.

Customization

Show author

Show step count

Show creation time

Show table of contents

import { CheckboxGroup, CheckboxGroupItem } from "stylus-ui/CheckboxGroup";

export default () => (
  <CheckboxGroup defaultValue={["author"]} label="Customization">
    <CheckboxGroupItem value="author" label="Show author" />
    <CheckboxGroupItem value="steps" label="Show step count" />
    <CheckboxGroupItem value="time" label="Show creation time" />
    <CheckboxGroupItem value="toc" label="Show table of contents" />
  </CheckboxGroup>
);

Orientation

Display checkboxes horizontally by passing orientation="horizontal".

Accessibility

High Contrast

Reduce Motion

import { CheckboxGroup, CheckboxGroupItem } from "stylus-ui/CheckboxGroup";

export default () => (
  <CheckboxGroup
    defaultValue={["reduce-motion"]}
    orientation="horizontal"
    label="Accessibility"
  >
    <CheckboxGroupItem value="high-contrast" label="High Contrast" />
    <CheckboxGroupItem value="reduce-motion" label="Reduce Motion" />
  </CheckboxGroup>
);

Disabled

The entire group can be disabled by using the disabled prop.

Customization

Show author

Show step count

Show creation time

Show table of contents

import { CheckboxGroup, CheckboxGroupItem } from "stylus-ui/CheckboxGroup";

export default () => (
  <CheckboxGroup
    defaultValue={["author", "steps"]}
    disabled
    label="Customization"
  >
    <CheckboxGroupItem value="author" label="Show author" />
    <CheckboxGroupItem value="steps" label="Show step count" />
    <CheckboxGroupItem value="time" label="Show creation time" />
    <CheckboxGroupItem value="toc" label="Show table of contents" />
  </CheckboxGroup>
);

The disabled prop can also be used to disable a specific CheckboxGroupItem.

Customization

Show author

Show step count

Show creation time

Show table of contents

import { CheckboxGroup, CheckboxGroupItem } from "stylus-ui/CheckboxGroup";

export default () => (
  <CheckboxGroup defaultValue={["author"]} label="Customization">
    <CheckboxGroupItem value="author" label="Show author" />
    <CheckboxGroupItem value="steps" label="Show step count" />
    <CheckboxGroupItem value="time" label="Show creation time" />
    <CheckboxGroupItem value="toc" label="Show table of contents" disabled />
  </CheckboxGroup>
);

Multiple selections

Unlike RadioGroup, CheckboxGroup allows multiple items to be selected simultaneously.

Customization

Show author

Show step count

Show creation time

Show table of contents

import { CheckboxGroup, CheckboxGroupItem } from "stylus-ui/CheckboxGroup";

export default () => (
  <CheckboxGroup defaultValue={["author", "steps"]} label="Customization">
    <CheckboxGroupItem value="author" label="Show author" />
    <CheckboxGroupItem value="steps" label="Show step count" />
    <CheckboxGroupItem value="time" label="Show creation time" />
    <CheckboxGroupItem value="toc" label="Show table of contents" />
  </CheckboxGroup>
);

Help text

Customization

Show author

Show step count

Show creation time

Show table of contents

Display links to each section

import { CheckboxGroup, CheckboxGroupItem } from "stylus-ui/CheckboxGroup";

export default () => (
  <CheckboxGroup defaultValue={["author", "steps"]} label="Customization">
    <CheckboxGroupItem value="author" label="Show author" />
    <CheckboxGroupItem value="steps" label="Show step count" />
    <CheckboxGroupItem value="time" label="Show creation time" />
    <CheckboxGroupItem
      value="toc"
      label="Show table of contents"
      helpText="Display links to each section"
    />
  </CheckboxGroup>
);

Controlled state

By default, CheckboxGroup is uncontrolled, meaning it manages its own state locally. To make it controlled, set value and onValueChange.

Customization

Show author

Show step count

Show creation time

Show table of contents

import { CheckboxGroup, CheckboxGroupItem } from "stylus-ui/CheckboxGroup";
import { useState } from "react";

export default () => {
  const [checkboxValues, setCheckboxValues] = useState(["toc"]);

  return (
    <CheckboxGroup
      value={checkboxValues}
      onValueChange={(values) => setCheckboxValues(values)}
      label="Customization"
    >
      <CheckboxGroupItem value="author" label="Show author" />
      <CheckboxGroupItem value="steps" label="Show step count" />
      <CheckboxGroupItem value="time" label="Show creation time" />
      <CheckboxGroupItem value="toc" label="Show table of contents" />
    </CheckboxGroup>
  );
};

Sizing

A smaller version of the checkbox group may be used by passing size="sm".

Customization

Show author

Show step count

Show creation time

Show table of contents

import { CheckboxGroup, CheckboxGroupItem } from "stylus-ui/CheckboxGroup";

export default () => (
  <CheckboxGroup defaultValue={["time"]} size="sm" label="Customization">
    <CheckboxGroupItem value="author" label="Show author" />
    <CheckboxGroupItem value="steps" label="Show step count" />
    <CheckboxGroupItem value="time" label="Show creation time" />
    <CheckboxGroupItem value="toc" label="Show table of contents" />
  </CheckboxGroup>
);

Keyboard Controls

Key	Description
`Tab`	Move focus into and out of the checkbox group
`↑` `↓`	Navigate between options (vertical layout)
`←` `→`	Navigate between options (horizontal layout)
`Space`	Toggle the focused option
`Home`	Jump to first option
`End`	Jump to last option

API Reference

`CheckboxGroup`

A set of checkable buttons where multiple options can be selected at a time.

`defaultValue`

string & CheckboxGroupValue | number & CheckboxGroupValue | readonly string[] & CheckboxGroupValue

Initial selected values when uncontrolled.

`disabled`

boolean = false

Disable all checkboxes in the group.

`label`

string

Label shown above the group.

`loop`

boolean = true

Whether keyboard focus loops within the group.

`name`

string

Name for the group (used for form submission).

`onValueChange`

(value: CheckboxGroupValue) => void

Called when the selection changes.

`orientation`

"horizontal" | "vertical" = "vertical"

Layout direction: vertical (stacked) or horizontal (row).

`required`

boolean = false

Require at least one selection.

`size`

"default" | "sm" = "default"

Size of each checkbox: default or sm.

`theme`

"light" | "dark" = "light"

Visual theme for the group and items.

`value`

CheckboxGroupValue

Controlled selected values (array of option values).

`CheckboxGroupItem`

An individual checkbox item within a CheckboxGroup. Must be rendered inside CheckboxGroup.

`value`

Required

string

Value for this option when selected (included in group value array).

`align`

"left" | "right" = "left"

Position of the label relative to the box: left or right.

`asChild`

boolean

`checked`

false | true | "indeterminate"

`children`

ReactNode

Additional content below the label.

`defaultChecked`

false | true | "indeterminate"

`helpText`

string

Helper text shown below the checkbox.

`label`

string

Label shown beside the checkbox.

`onCheckedChange`

(checked: CheckedState) => void

`required`

boolean

`size`

"default" | "sm" = "default"

Override group size for this item.

`theme`

"light" | "dark" = "light"

Override group theme for this item.