Skip to content
Stylus UI

Checkbox Group

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

Usage

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “API Reference”

CheckboxGroup

Section titled “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

Section titled “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

Section titled “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