Checkbox React component for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

Usage

Import Checkbox from @/components/ui/checkbox.

import { useState } from "react"
import { Checkbox, CheckboxGroup } from "@/components/ui/checkbox"

const AMENITIES = [
  { value: "parking", label: "Parking" },
  { value: "balcony", label: "Balcony" },
  { value: "elevator", label: "Elevator" },
  { value: "laundry", label: "In-unit laundry" },
]

export function OrderConsent({ showError }: { showError: boolean }) {
  const [accepted, setAccepted] = useState(false)
  const [amenities, setAmenities] = useState<string[]>(["parking"])
  return (
    <form className="flex flex-col gap-4">
      <Checkbox
        name="terms"
        required
        checked={accepted}
        onCheckedChange={(checked) => setAccepted(checked === true)}
        label="I agree to the Terms and conditions"
        error={showError && !accepted ? "You need to accept the terms." : undefined}
      />
      <CheckboxGroup
        label="Amenities"
        name="amenities"
        columns={2}
        options={AMENITIES}
        value={amenities}
        onValueChange={setAmenities}
      />
    </form>
  )
}

Props

• labeldefault ""
  ReactNode

  Text beside the box. The whole row is one <label>, so clicking the text, the description or the empty space toggles the box. A link inside it opens without toggling.

• descriptiondefault ""
  ReactNode

  A second line under the label, in the muted caption style. It is kept out of the box's name and linked with aria-describedby, so screen readers read it after the label.

• errordefault ""
  ReactNode

  A message under the row, lined up with the label, that slides in and marks the box invalid (red border, aria-invalid). "", false and null are no error. A box without a label only turns red; wrap it in a Field to show the text.

• requireddefault false
  boolean

  Shows the red mark after the label, sets aria-required, and inside a native form blocks submission while unchecked (through Radix's hidden input).

• invaliddefault false
  boolean

  The red border and aria-invalid without a message, for forms that show errors elsewhere. Inherits from a parent Field.

• disableddefault false
  boolean

  Dims the row to 50% and blocks it. A disabled Field or FieldGroup around it disables it too.

• readOnlydefault false
  boolean

  Shows the value but ignores clicks and Space, with no hover or press feedback; the box keeps focus and sets aria-readonly.

• defaultCheckeddefault false
  boolean | "indeterminate"

  The starting state while uncontrolled: true, false or "indeterminate" (a dash, aria-checked="mixed").

• checked
  boolean | "indeterminate"

  The state while controlled. Pair it with onCheckedChange.

• onCheckedChange
  (checked: boolean | "indeterminate") => void

  Called with the next state. Clicking an indeterminate box makes it true, like Radix.

• sizedefault "md"
  "sm" | "md" | "lg"

  Box 16 / 18 / 20px with a 12 / 14 / 16px check and a 13 / 14 / 15px label. The box centers on the label's first line at every size.

• tonedefault "neutral"
  "neutral" | "brand" | "success" | "warning" | "danger" | "info"

  The checked fill (and the card ring and icon tile). neutral is black in light mode and white in dark mode; keep brand for the one place it means something.

• colordefault ""
  string

  Any CSS color. Replaces the tone; the check turns black or white by the color's lightness. Leave empty to use the tone.

• radiusdefault "md"
  "none" | "sm" | "md" | "lg" | "full"

  Box corners, scaled with the size: md is 4 / 5 / 6px, full makes a round checkbox.

• variantdefault "default"
  "default" | "card"

  card turns the row into a soft-filled tile with the box at the top end, an optional icon tile, and a ring in the tone when checked. For rich choices like paid extras.

• labelPositiondefault "end"
  "end" | "start"

  start puts the label first and the box at the end of a full-width row, like a settings list. Cards ignore it.

• icon
  ReactNode

  Cards: the leading icon in a 40px tile that takes the tone when checked. Rows: a thumbnail or avatar between the box and the text (the row then centers).

• namedefault ""
  string

  Form field name. Inside a <form> Radix renders a hidden input that submits value while checked and returns to its first state when the form resets. The playground sits in a real form.

• valuedefault "on"
  string

  What the form submits while the box is checked.

• id
  string

  The box's id. Defaults to useId(); inside a Field the Field's id wins, so its label toggles the box.

• classNames
  Partial<Record<"field" | "box" | "indicator" | "content" | "label" | "description" | "error" | "icon", string>>

  Extra classes for the parts: field is the label row (or the card), box the button, indicator the check svg. Padding for list rows goes on field so the padding stays clickable.

• className
  string

  Classes for the outermost element: the wrapper around the row and its message, or the box itself when there is no label. ref and every other prop (aria-*, data-*, onBlur, form) go to the box, a <button role="checkbox">, so form libraries can focus it.

Parts

FAQ

Used in

More React input components