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.

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

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

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

align

"left" | "right" = "left"

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

---

asChild

boolean

---

checked

false | true | "indeterminate"

---

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"

Checkbox size: default (20px) or sm (16px).

---

theme

"light" | "dark" = "light"

Visual theme for the box and label.

---