@mshafiqyajid/react-checkbox
Headless checkbox hook + styled component. Indeterminate (tri-state) support, three sizes, four tones, label position, full keyboard support (Space toggles), animated check + indeterminate icons.
Playground #
I agree to the terms
Props
TSX
import { CheckboxStyled } from "@mshafiqyajid/react-checkbox/styled";
import "@mshafiqyajid/react-checkbox/styles.css";
<CheckboxStyled
checked={checked}
onChange={setChecked}
label="I agree to the terms"
/>Props
TSX
import { CheckboxGroup, CheckboxStyled } from "@mshafiqyajid/react-checkbox/styled";
import "@mshafiqyajid/react-checkbox/styles.css";
<CheckboxGroup
value={groupValues}
onChange={setGroupValues}
label="Notify me about…"
/>Install #
npm install @mshafiqyajid/react-checkboxQuick start #
import { CheckboxStyled } from "@mshafiqyajid/react-checkbox/styled";
import "@mshafiqyajid/react-checkbox/styles.css";
<CheckboxStyled label="I agree to the terms" tone="primary" />Indeterminate #
Pass "indeterminate" to checked or defaultChecked for tri-state. Clicking from indeterminate moves to checked. onChange always emits boolean (never "indeterminate") — typically you choose what state to land in based on the action that triggered the indeterminate value.
<CheckboxStyled
checked="indeterminate"
onChange={(c) => console.log(c)}
/>Headless #
import { useCheckbox } from "@mshafiqyajid/react-checkbox";
const { checkboxProps, isChecked, isIndeterminate } = useCheckbox({
defaultChecked: false,
});
return (
<button {...checkboxProps}>
{isIndeterminate ? "—" : isChecked ? "✓" : ""}
</button>
);CheckboxGroup #
Wrap multiple checkboxes in CheckboxGroup to manage them as a set. Each checkbox must have a value prop. The group tracks a string[] of checked values.
import { CheckboxGroup, CheckboxStyled } from "@mshafiqyajid/react-checkbox/styled";
const [values, setValues] = useState<string[]>(["a"]);
<CheckboxGroup value={values} onChange={setValues}>
<CheckboxStyled value="a" label="Option A" />
<CheckboxStyled value="b" label="Option B" />
<CheckboxStyled value="c" label="Option C" />
</CheckboxGroup>API #
| Prop | Type | Default | Description |
|---|---|---|---|
| checked | boolean | "indeterminate" | — | Controlled state |
| defaultChecked | boolean | "indeterminate" | false | Uncontrolled initial state |
| onChange | (checked: boolean) => void | — | Always emits boolean |
| value | string | — | Value used when inside a CheckboxGroup |
| size | "sm" | "md" | "lg" | "md" | Size |
| tone | "neutral" | "primary" | "success" | "danger" | "primary" | Color when checked |
| label | ReactNode | — | Label |
| description | ReactNode | — | Helper text below the label |
| error | ReactNode | — | Error message — flips tone to danger and renders below |
| labelPosition | "left" | "right" | "right" | Label side |
| card | boolean | false | Bordered card; whole row becomes clickable |
| required | boolean | false | Append a red asterisk to the label |
| invalid | boolean | false | Force invalid (danger) state without inline error text |
| disabled | boolean | false | Disable |
| name | string | — | Native form name attribute |
| className | string | — | Extra class on the root element |
| style | CSSProperties | — | Inline style override |