Skip to content
Stylus UI

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.

 
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".

 
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.

 
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.

 
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.

 
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

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.

 
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".

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

API Reference

CheckboxGroup

Contains all the parts of a checkbox group.

Inherits properties from HTMLElement.

Prop
Type
Default
children ReactNode
defaultValue string[]
disabled boolean
label string
loop boolean true
name string
onValueChange (value: string[]) => void
orientation "horizontal""vertical" "vertical"
required boolean
size "default""sm" "default"
theme "light""dark" "light"
value string[]

CheckboxGroupItem

An item in the group that can be checked. See Checkbox for more details about individual checkbox behavior. An input will also render when used within a form to ensure events propagate correctly.

Inherits properties from HTMLButtonElement.

Prop
Type
Default
value string
children ReactNode
disabled boolean
label string
size "default""sm" "default"
theme "light""dark" "light"

Keyboard Controls

KeyDescription
TabMove focus into and out of the checkbox group
↑ ↓Navigate between options (vertical layout)
← →Navigate between options (horizontal layout)
SpaceToggle the focused option
HomeJump to first option
EndJump to last option