Checkbox

Single-choice control for binary selections, consent, and form fields.

Installation

npx shadcn@latest add @iconiq/r-checkbox

File Structure

Usage

"use client";

import { useState } from "react";
import { Checkbox } from "@/components/ui/r-checkbox";

export function CheckboxPreview() {
  const [checked, setChecked] = useState(true);

  return (
    <div className="w-full max-w-sm">
      <Checkbox
        checked={checked}
        description="You can turn this off anytime in account settings."
        id="release-updates"
        label="Email me when the next release ships"
        name="release-updates"
        onCheckedChange={setChecked}
        value="yes"
      />
    </div>
  );
}

Props

Props
Description

Checkbox

checked

Controlled checked state. Pass true, false, or "indeterminate" for partial selection rows such as select-all headers.

Type boolean | "indeterminate"

defaultChecked

Initial state for uncontrolled usage. It is only read on the first render.

Type boolean | "indeterminate"·Default false

onCheckedChange

Called with the next boolean value whenever the user toggles the checkbox. Indeterminate clicks resolve to true.

Type (checked: boolean) => void

label

Optional label rendered beside the control. When provided with description, both sit inside a native label element linked by htmlFor.

Type React.ReactNode

description

Optional helper copy rendered under the label and linked through aria-describedby.

Type React.ReactNode

labelClassName

Merged onto the label text wrapper.

Type string

descriptionClassName

Merged onto the description text wrapper.

Type string

disabled

Disables interaction and applies reduced opacity to the full row.

Type boolean·Default false

readOnly

Shows the current state without allowing toggles. Useful for locked consent rows.

Type boolean·Default false

required

Forwards native required validation to the hidden checkbox input and appends a visual asterisk to the label.

Type boolean·Default false

invalid

Applies destructive border styling and aria-invalid for form validation feedback.

Type boolean·Default false

name

Input name submitted with native forms.

Type string

value

Value submitted when the checkbox is checked.

Type string

form

Associates the hidden input with a form element by id when the checkbox renders outside the form.

Type string

size

Adjusts box, icon, label, and row spacing together.

Type "sm" | "default" | "lg"·Default "default"

id

Stable id for the control. When omitted, the component generates one and uses it for label association.

Type string

className

Merged onto the outer row wrapper so you can position the checkbox in your layout.

Type string

Motion and accessibility

Visual feedback comes from Motion while checkbox semantics travel through the underlying primitive and hidden input.

The box animates its border and fill between theme tokens, then the checkmark or minus icon draws based on the next state.

Tap feedback briefly compresses the control unless disabled, readOnly, or prefers-reduced-motion is active.

The label subtly dims when the row is fully checked. Indeterminate rows keep full label opacity.

Checkbox groups for multi-select lists are available via b-checkbox-group. There is no r-checkbox-group registry entry yet.

Registry bundle

Install the exact registry entry shown on the right when you want the component file and its declared runtime dependencies together.

Dependencies: @base-ui/react/checkbox, motion.

Contact

Additionally, if you find any bug or issue, feel free to raise an issue.