FormCheckbox

PreviousNext

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

This field is required
'use client';

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

export function FormCheckboxDemo() {
  const [checked1, setChecked1] = useState(false);
  const [checked2, setChecked2] = useState(false);

  return (
    <div className="space-y-4">
      <FormCheckbox
        name="demo"
        value="demo-value"
        checked={checked1}
        onChange={(e) => setChecked1(e.target.checked)}
      >
        Basic checkbox
      </FormCheckbox>
      <FormCheckbox
        name="demo2"
        value="demo-value2"
        checked={checked2}
        onChange={(e) => setChecked2(e.target.checked)}
        validationStatus="error"
        errorMessage="This field is required"
      >
        Checkbox with validation
      </FormCheckbox>
    </div>
  );
}

Installation

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

Usage

import { FormCheckbox } from '@/docs/lib/ui/forms/checkboxes/form-checkbox';
import { useState } from 'react';
 
export function Component() {
  const [checked, setChecked] = useState(false);
 
  return (
    <FormCheckbox
      name="name"
      value="value"
      checked={checked}
      onChange={(e) => setChecked(e.target.checked)}
      validationStatus="default"
    >
      Checkbox label
    </FormCheckbox>
  );
}

With Validation

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

API Reference

FormCheckbox

PropTypeDefaultDescription
idstring?generatedThe ID attribute for the checkbox
namestringidThe name attribute for the checkbox
classNamestringundefinedAdditional CSS classes for container
dataTestIdstringundefinedThe data-testid attribute for testing
disabledbooleanfalseWhether the checkbox is disabled
checkedbooleanfalseWhether the checkbox is checked
valuestringundefinedThe value attribute for the checkbox
sizestring"size-24"The size class for the checkbox
colorColors"black"The color of the checkbox
tabIndexnumber0The tab index for keyboard navigation
validationStatus"default" | "error" | "success""default"Validation status for styling
errorMessagestringundefinedError message to display when status=error
childrenReactNodeundefinedLabel content displayed next to checkbox
onChange(event: ChangeEvent<HTMLInputElement>) => voidundefinedNative onChange handler

Examples

Disabled State

'use client';

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

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

Relationship to Checkbox

FormCheckbox is a wrapper around the Checkbox component that provides:

  • Label support via children prop (displayed next to the checkbox)
  • Built-in validation status handling
  • Error message display with icon
  • Container structure with data-testid support

When to use each:

  • Use FormCheckbox when building forms with validation requirements
  • Use Checkbox when you need a simple checkbox visual without form wrapper features

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 messages appear below the checkbox when validationStatus="error" and errorMessage is provided.
  • Disabled Priority: Disabled state takes precedence over validation states. When disabled, validation styling is replaced with disabled styling.
  • Label Rendering: The children prop renders as label text next to the checkbox within a <label> element for proper accessibility.
  • Client Component: This component uses React hooks and must be used in a client component (requires "use client" directive in Next.js App Router).