Forms
Checkbox
Checkbox is a single boolean field with built-in `label`, `text`, `helpText`, and `controlPosition` — matching Input field chrome. Use CheckboxGroup for multi-select lists.
Installation
npx shadcn add https://rck.vibeboxph.com//r/checkbox.jsonLive preview & controls
Product news about once a month.
Controls
<Checkbox
label="Preferences"
text="Email me updates"
helpText="Product news about once a month."
/>Anatomy
CheckboxControlThe bare toggle (exported for advanced composition).CheckboxStandalone labeled field with top label, inline text, and help text.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
| checked / defaultChecked | boolean | "indeterminate" | — | Controlled / uncontrolled checked state. |
| onCheckedChange | (checked: boolean | "indeterminate") => void | — | Fires when the value changes. |
| label | React.ReactNode | — | Top field label — matches Input and Textarea. |
| text | React.ReactNode | — | Inline label text beside the checkbox. |
| helpText | React.ReactNode | — | Supplementary help text linked via `aria-describedby`. |
| controlPosition | "start" | "end" | start | Places the control at inline-start or inline-end (RTL-aware). |
| disabled | boolean | — | Native disabled state. |
| required | boolean | — | Marks the checkbox as required in forms. |
Accessibility
- Uses the built-in Checkbox primitive with `role="checkbox"`, `aria-checked`, and Space to toggle.
- Checkbox wires `htmlFor`/`id` and `aria-describedby` automatically.
Source
registry/rck/ui/checkbox.tsx
"use client";
import * as React from "react";
import * as CheckboxPrimitive from "@/registry/rck/primitives/checkbox";
import { Check } from "@/lib/icons";
import { cn } from "@/lib/utils";
import { BooleanFieldLayout, type ControlPosition } from "@/registry/rck/ui/field-chrome";
export type CheckboxControlProps = React.ComponentPropsWithoutRef<
typeof CheckboxPrimitive.Root
>;
/** Bare checkbox control — use `Checkbox` for a labeled field or compose inside groups. */
export const CheckboxControl = React.forwardRef<
React.ComponentRef<typeof CheckboxPrimitive.Root>,
CheckboxControlProps
>(({ className, ...props }, ref) => (
<CheckboxPrimitive.Root
ref={ref}
data-slot="checkbox-control"
className={cn(
"group border-border-strong bg-background size-4 shrink-0 rounded-[4px] border shadow-sm " +
"focus-visible:ring-ring transition-colors focus-visible:ring-2 focus-visible:outline-none " +
"focus-visible:ring-offset-background focus-visible:ring-offset-2 " +
"disabled:cursor-not-allowed disabled:opacity-50 " +
"data-[state=checked]:border-primary data-[state=checked]:bg-primary data-[state=checked]:text-primary-foreground",
className,
)}
{...props}
>
<CheckboxPrimitive.Indicator
data-slot="checkbox-indicator"
className="flex items-center justify-center text-current"
>
<Check className="size-3" aria-hidden="true" />
</CheckboxPrimitive.Indicator>
</CheckboxPrimitive.Root>
));
CheckboxControl.displayName = "CheckboxControl";
export function Checkbox({
className,
containerClassName,
label,
text,
helpText,
error,
required,
controlPosition = "start",
id,
disabled,
...props
}: CheckboxControlProps & {
/** Top field label — matches Input and Textarea. */
label?: React.ReactNode;
/** Text beside the checkbox control. */
text?: React.ReactNode;
helpText?: React.ReactNode;
error?: React.ReactNode;
required?: boolean;
controlPosition?: ControlPosition;
id?: string;
containerClassName?: string;
}) {
return (
<BooleanFieldLayout
label={label}
text={text}
helpText={helpText}
error={error}
required={required}
controlPosition={controlPosition}
disabled={disabled}
id={id}
className={className}
containerClassName={containerClassName}
>
{({ id: fieldId, describedBy, disabled: fieldDisabled }) => (
<CheckboxControl
id={fieldId}
disabled={fieldDisabled}
aria-describedby={describedBy}
aria-invalid={error ? true : undefined}
required={required}
{...props}
/>
)}
</BooleanFieldLayout>
);
}
/** @deprecated Use `Checkbox` instead. */
export const CheckboxField = Checkbox;
/** @deprecated Use `CheckboxControl` instead. */
export const CheckboxRoot = CheckboxControl;
registry/rck/ui/field-chrome.tsx
import * as React from "react";
import { cva, type VariantProps } from "@/lib/cva";
import { cn } from "@/lib/utils";
export const fieldWrapperVariants = cva(
"flex w-full items-center gap-2 rounded-md border bg-background px-3 shadow-sm " +
"transition-colors has-[input:disabled]:cursor-not-allowed has-[input:disabled]:opacity-50 " +
"has-[textarea:disabled]:cursor-not-allowed has-[textarea:disabled]:opacity-50",
{
variants: {
size: {
sm: "h-8 text-[10px]",
md: "h-[39px] text-[11px]",
lg: "h-11 text-xs",
},
invalid: {
true: "border-destructive focus-within:ring-2 focus-within:ring-destructive/40",
false:
"border-border-strong focus-within:border-primary focus-within:ring-2 focus-within:ring-ring/30",
},
},
defaultVariants: {
size: "md",
invalid: false,
},
},
);
/** Built-in field label — shared by Input, Textarea, and boolean field wrappers. */
export function FieldLabel({
className,
required,
children,
...props
}: React.LabelHTMLAttributes<HTMLLabelElement> & { required?: boolean }) {
return (
<label
data-slot="field-label"
className={cn("text-foreground text-sm leading-none font-medium", className)}
{...props}
>
{children}
{required && <span className="text-destructive ml-0.5">*</span>}
</label>
);
}
export function FieldMessage({
className,
invalid,
...props
}: React.HTMLAttributes<HTMLParagraphElement> & { invalid?: boolean }) {
return (
<p
data-slot="field-message"
className={cn(
"text-xs",
invalid ? "text-destructive" : "text-muted-foreground",
className,
)}
{...props}
/>
);
}
export type ControlPosition = "start" | "end";
export interface BooleanGroupOption {
value: string;
/** Inline label beside the control. */
text: string;
disabled?: boolean;
helpText?: React.ReactNode;
}
export interface BooleanFieldLayoutProps {
label?: React.ReactNode;
text?: React.ReactNode;
helpText?: React.ReactNode;
error?: React.ReactNode;
required?: boolean;
/** Places the control at inline-start (default) or inline-end — flips automatically in RTL. */
controlPosition?: ControlPosition;
disabled?: boolean;
id?: string;
className?: string;
containerClassName?: string;
children: (args: {
id: string;
describedBy?: string;
disabled?: boolean;
}) => React.ReactNode;
}
export function BooleanFieldLayout({
label,
text,
helpText,
error,
required,
controlPosition = "start",
disabled,
id: providedId,
className,
containerClassName,
children,
}: BooleanFieldLayoutProps) {
const generatedId = React.useId();
const id = providedId ?? generatedId;
const helpTextId = helpText && !error ? `${id}-help-text` : undefined;
const errorId = error ? `${id}-error` : undefined;
const describedBy = cn(helpTextId, errorId) || undefined;
const control = children({ id, describedBy, disabled });
return (
<div
data-slot="boolean-field"
className={cn("flex flex-col gap-1.5", containerClassName)}
>
{label && (
<FieldLabel htmlFor={id} required={required}>
{label}
</FieldLabel>
)}
<div
className={cn(
"flex w-full items-start gap-2",
controlPosition === "end" && "flex-row-reverse justify-between",
className,
)}
>
{control}
{text && (
<label
htmlFor={id}
className={cn(
"text-foreground text-sm leading-none font-medium",
controlPosition === "end" && "flex-1",
disabled && "cursor-not-allowed opacity-50",
)}
>
{text}
</label>
)}
</div>
{helpText && !error && <FieldMessage id={helpTextId}>{helpText}</FieldMessage>}
{error && (
<FieldMessage id={errorId} invalid role="alert">
{error}
</FieldMessage>
)}
</div>
);
}
export type FieldWrapperVariantProps = VariantProps<typeof fieldWrapperVariants>;
Related examples
Labeled fieldsStandalone checkbox with top label, inline text, and disabled states.
Control positionInline-start vs inline-end checkbox placement.