Checkbox

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.

Accessibility

To make the label clickable, set the id prop so that the label is associated with the checkbox. Each id on a page should be unique.

Accept terms and conditions

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.

Accept terms and conditions

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

Accept terms and conditions

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

Dark mode

Set theme to dark to use the dark theme.

Enable dark mode

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="Enable dark mode"
        theme="dark"
      />
    </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.

This checkbox is uncontrolled

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

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

Indeterminate checkboxes must be controlled

Uncontrolled checkboxes (using defaultChecked) cannot use the indeterminate state. If you need to represent an indeterminate state, set checked to "indeterminate" and respond to changes with onCheckedChange.

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