Skip to content
Stylus UI

Checkbox

A control that allows the user to toggle between checked and not checked.

Usage

To create a checkbox, import Checkbox and set the checked and onCheckedChange props. Checkboxes can be true, false, or "indeterminate".

 
import { Checkbox } from "stylus-ui/Checkbox";
import { useState } from "react";


export default () => {
  const [checked, setChecked] = useState("indeterminate");
  return <Checkbox checked={checked} onCheckedChange={setChecked} />;
};

Label

An accessible label can be displayed alongside a checkbox by passing a label.

 
import { Checkbox } from "stylus-ui/Checkbox";
import { useState } from "react";


export default () => {
  const [checked, setChecked] = useState(false);


  return (
    <Checkbox
      checked={checked}
      onCheckedChange={setChecked}
      label="Accept terms and conditions"
    />
  );
};

Help text

Display informative, secondary text beneath a label by passing helpText.

You agree to our Terms of Service and Privacy Policy.

 
import { Checkbox } from "stylus-ui/Checkbox";
import { useState } from "react";


export default () => {
  const [checked, setChecked] = useState(false);


  return (
    <div className="max-w-[260px]">
      <Checkbox
        checked={checked}
        onCheckedChange={setChecked}
        label="Accept terms and conditions"
        helpText="You agree to our Terms of Service and Privacy Policy."
      />
    </div>
  );
};

Sizing

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

You agree to our Terms of Service and Privacy Policy.

 
import { Checkbox } from "stylus-ui/Checkbox";
import { useState } from "react";


export default () => {
  const [checked, setChecked] = useState(false);


  return (
    <div className="max-w-[260px]">
      <Checkbox
        checked={checked}
        onCheckedChange={setChecked}
        label="Accept terms and conditions"
        helpText="You agree to our Terms of Service and Privacy Policy."
        size="sm"
      />
    </div>
  );
};

Uncontrolled

In most cases, you’ll want to control the state of Checkbox by passing checked and onCheckedChange. To use Checkbox as an uncontrolled component, pass defaultChecked instead of checked.

 
import { Checkbox } from "stylus-ui/Checkbox";


export default () => {
  return (
    <Checkbox
      defaultChecked={true}
      id="uncontrolled-example"
      label="This checkbox is uncontrolled"
    />
  );
};

Groups

To display a group of related checkboxes, use CheckboxGroup.

API Reference

Checkbox

Inherits properties from HTMLButtonElement.

Prop
Type
Default
align "left""right" "left"
asChild boolean false
checked boolean"indeterminate"
defaultChecked boolean"indeterminate"
disabled boolean
helpText string
label string
name string
onCheckedChange (checked: boolean | "indeterminate") => void
required boolean
size "default""sm" "default"
theme "light""dark" "light"
value string