Checkbox Button

The CheckboxButton component is a flexible, styled checkbox UI that supports both single and multiple selection modes. It can also integrate with form libraries (such as React Hook Form) and includes built-in variants for size, rounding, and error states.

import { CheckboxButton } from "tawuniya/components";

👉 View in Storybook

---

Props

Base Props (applies to both single and multiple modes)

Prop	Type	Default	Description
size	"sm" | "md" | "lg"	"md"	Size variant for padding and spacing.
rounded	"sm" | "md" | "lg" | "xl" | "full"	"xl"	Border-radius variant.
fullWidth	boolean	false	Makes the checkbox occupy full width.
description	string	—	Optional text shown below the label.
info	React.ReactNode	—	Optional info element shown under the checkbox (with info icon).
disabled	boolean	false	Disables the checkbox and applies a faded style.
className	string	—	Additional Tailwind classes for wrapper.
error	string	—	Error message displayed below the checkbox.
form	{ controller: any; control: any; name: string; }	—	For form integration with React Hook Form.

---

Single Mode Props

When multiple is not set (or false):

Prop	Type	Description
label	string	Checkbox label text.
id	string	HTML id for checkbox input.
checked	boolean	Current checked state.
onChange	(checked: boolean) => void	Callback when state changes.

---

Multiple Mode Props

When multiple is true:

Prop	Type	Description
items	Array<{ id: string; label: string; description?: string }>	List of checkbox items.
checked	string[]	Array of selected item IDs.
onChange	(checked: string[]) => void	Callback when selection changes.

---

Usage

Single Checkbox

import { useState } from "react";
import { CheckboxButton } from "tawuniya/components";

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

  return (
    <CheckboxButton
      label="Accept Terms"
      id="accept-terms"
      checked={checked}
      onChange={setChecked}
      description="You must agree before continuing."
    />
  );
}

---

Multiple Checkboxes

import { useState } from "react";
import { CheckboxButton } from "tawuniya/components";

export default function MultipleExample() {
  const [selected, setSelected] = useState<string[]>([]);

  return (
    <CheckboxButton
      multiple
      items={[
        { id: "opt1", label: "Option One" },
        { id: "opt2", label: "Option Two" },
        { id: "opt3", label: "Option Three" },
      ]}
      checked={selected}
      onChange={setSelected}
      info="You can select more than one option."
    />
  );
}

---

With Form Integration (React Hook Form)

import { useForm, Controller } from "react-hook-form";
import { CheckboxButton } from "tawuniya/components";

export default function FormExample() {
  const { control, handleSubmit } = useForm({
    defaultValues: { terms: false },
  });

  const onSubmit = (data: any) => {
    console.log(data);
  };

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <CheckboxButton
        label="I agree to the terms"
        form={{ controller: Controller, control, name: "terms" }}
        error="This field is required."
      />
      <button type="submit">Submit</button>
    </form>
  );
}

---

Variants

• Size

  • sm → Compact padding
  • md → Medium padding
  • lg → Large padding

• Rounded

  • sm, md, lg, xl, full

• States

  • disabled → Prevents interaction
  • error → Highlights in red and shows error message
  • info → Displays helper information with icon

---

Accessibility

• Uses semantic <label> and checkbox input.
• aria-live="assertive" for error messages.
• Disabled state applies correct aria-disabled.

---

Notes

• When using multiple mode, ensure checked is an array of selected IDs.
• For form usage, pass form with Controller and control from React Hook Form.

---

If you’d like, I can add a “Props Table” auto-generated from TypeScript types so the docs always match the code without manual updates. That way your MD file stays in sync even after refactors.