Checkbox

PreviousNext

A form-friendly checkbox component with built-in validation support

This field is required
'use client';

import { Checkbox } from '@/ui/forms/checkboxes/Checkbox';
import { useState } from 'react';

export function CheckboxDemo() {
  const [checked, setChecked] = useState(false);
  const [error, setError] = useState('This field is required');

  return (
    <div className="space-y-4">
      <Checkbox
        name="terms"
        value="accepted"
        checked={checked}
        onChange={(_, value) => {
          setChecked(value);
          setError(value ? '' : 'This field is required');
        }}
        validationStatus={error ? 'error' : 'default'}
        errorMessage={error}
      >
        I agree to the terms and conditions
      </Checkbox>
    </div>
  );
}

Installation

npx shadcn@latest add https://develop.trident-ui.pro.clubmed/r/checkbox.json

Usage

import { Checkbox } from '@/docs/lib/ui/forms/checkboxes/Checkbox';
import { useState } from 'react';
 
export function Component() {
  const [checked, setChecked] = useState(false);
 
  return (
    <Checkbox
      name="name"
      value="value"
      checked={checked}
      onChange={(_, value) => setChecked(value)}
    />
  );
}

With Label

import { Checkbox } from '@/docs/lib/ui/forms/checkboxes/Checkbox';
import { useState } from 'react';
 
export function Component() {
  const [checked, setChecked] = useState(false);
 
  return (
    <Checkbox name="name" value="value" checked={checked} onChange={(_, value) => setChecked(value)}>
      Checkbox label
    </Checkbox>
  );
}

With Validation

import { Checkbox } from '@/docs/lib/ui/forms/checkboxes/Checkbox';
import { useState } from 'react';
 
export function Component() {
  const [checked, setChecked] = useState(false);
  const [error, setError] = useState('This field is required');
 
  return (
    <Checkbox
      name="terms"
      value="accepted"
      checked={checked}
      onChange={(_, value) => {
        setChecked(value);
        setError(value ? '' : 'This field is required');
      }}
      validationStatus={error ? 'error' : 'default'}
      errorMessage={error}
    >
      I agree to the terms and conditions
    </Checkbox>
  );
}

API Reference

Checkbox

PropTypeDefaultDescription
idstringgeneratedID of the underlying input
namestringidName of the underlying input
data-testidstringundefinedThe data-testid attribute for testing
childrenReactNodeundefinedOptional label content displayed next to the checkbox
checkedbooleanundefinedControlled checked state
defaultCheckedbooleanundefinedUncontrolled initial checked state
disabledbooleanfalseDisables interactions
valuestringundefinedInput value
onChange(event: Event, value: boolean) => voidundefinedChange handler receiving browser event, checked value
sizestring"size-24"Size utility class for the checkbox box
colorColors"black"Border/text color token used by the checkbox box
validationStatus"default" | "error" | "success""default"Validation state used for styling and error display
errorMessagestringundefinedError text shown when validationStatus="error"
classNamestringundefinedExtra CSS classes
tabIndexnumber0Input tab order

Examples

'use client';

import { Checkbox } from '@/ui/forms/checkboxes/Checkbox';

export function CheckboxDisabledDemo() {
  return (
    <div className="space-y-4">
      <Checkbox name="disabled-unchecked" value="disabled" disabled>
        Disabled unchecked
      </Checkbox>
      <Checkbox name="disabled-checked" value="disabled-checked" disabled checked>
        Disabled checked
      </Checkbox>
    </div>
  );
}

Notes

  • Controlled Component: This is a fully controlled component. You must manage the checked state and onChange handler in the parent component.
  • Validation Display: Error message appears below the checkbox when validationStatus="error" and errorMessage is provided.
  • Disabled Priority: Disabled state takes precedence over validation states.
  • Label Rendering: The children prop renders next to the checkbox in a <label> when provided.
  • Client Component: This component uses React hooks and must be used in a client component (requires "use client" directive in Next.js App Router).