Forms

CheckboxGroup

CheckboxGroup is a full form field — pass `label`, `helpText`, `error`, and an `options` array. Value is a `string[]` of selected option values.

Installation

npx shadcn add https://rck.vibeboxph.com//r/checkbox-group.json

Live preview & controls

Notification channels

Email notifications

SMS alerts

Push notifications

In-app messages

Choose every channel you want.

ControlsDisabledOffControl positionOrientation

<CheckboxGroup label="Notification channels" defaultValue={["email", "push"]} options={[...]} />

Anatomy

CheckboxGroupField container with label, option list, and group help text.

Props

Prop	Type	Default	Description
options*	{ value: string; text: string; disabled?: boolean; helpText?: React.ReactNode }[]	—	Multi-select option list.
value / defaultValue	string[]	—	Controlled / uncontrolled selected values.
onValueChange	(value: string[]) => void	—	Fires when the selection changes.
label	React.ReactNode	—	Top field label.
helpText	React.ReactNode	—	Group-level help text.
error	React.ReactNode	—	Error text; sets `aria-invalid` on the group.
orientation	"vertical" \| "horizontal"	vertical	Stack options vertically or wrap horizontally.
controlPosition	"start" \| "end"	start	Inline-start/end placement for each option.

Accessibility

Uses `role="group"` with `aria-labelledby` for the shared field label.
Each option checkbox is individually labeled and keyboard accessible.

Source

registry/rck/ui/checkbox-group.tsx

"use client";

import * as React from "react";
import { cn } from "@/lib/utils";
import { useControllableState } from "@/hooks/use-controllable-state";
import { CheckboxControl } from "@/registry/rck/ui/checkbox";
import {
  BooleanFieldLayout,
  FieldLabel,
  FieldMessage,
  type BooleanGroupOption,
  type ControlPosition,
} from "@/registry/rck/ui/field-chrome";

export type { BooleanGroupOption as CheckboxGroupOption } from "@/registry/rck/ui/field-chrome";

export interface CheckboxGroupProps {
  label?: React.ReactNode;
  helpText?: React.ReactNode;
  error?: React.ReactNode;
  required?: boolean;
  containerClassName?: string;
  className?: string;
  id?: string;
  disabled?: boolean;
  options: ReadonlyArray<BooleanGroupOption>;
  value?: string[];
  defaultValue?: string[];
  onValueChange?: (value: string[]) => void;
  controlPosition?: ControlPosition;
  orientation?: "vertical" | "horizontal";
}

export function CheckboxGroup({
  label,
  helpText,
  error,
  required,
  containerClassName,
  className,
  id: providedId,
  disabled,
  options,
  value,
  defaultValue = [],
  onValueChange,
  controlPosition = "start",
  orientation = "vertical",
}: CheckboxGroupProps) {
  const [selected, setSelected] = useControllableState<string[]>({
    prop: value,
    defaultProp: defaultValue,
    onChange: onValueChange,
  });

  const generatedId = React.useId();
  const groupId = providedId ?? generatedId;
  const helpTextId = helpText && !error ? `${groupId}-help-text` : undefined;
  const errorId = error ? `${groupId}-error` : undefined;
  const describedBy = cn(helpTextId, errorId) || undefined;

  function toggle(optionValue: string, checked: boolean | "indeterminate") {
    if (checked === "indeterminate") return;
    setSelected((current) =>
      checked
        ? current.includes(optionValue)
          ? current
          : [...current, optionValue]
        : current.filter((item) => item !== optionValue),
    );
  }

  return (
    <div
      data-slot="checkbox-group-container"
      className={cn("flex flex-col gap-1.5", containerClassName)}
    >
      {label && (
        <FieldLabel id={`${groupId}-label`} required={required}>
          {label}
        </FieldLabel>
      )}
      <div
        role="group"
        id={groupId}
        data-slot="checkbox-group"
        aria-labelledby={label ? `${groupId}-label` : undefined}
        aria-describedby={describedBy}
        aria-invalid={error ? true : undefined}
        className={cn(
          orientation === "horizontal" ? "flex flex-wrap gap-4" : "grid gap-2",
          className,
        )}
      >
        {options.map((option) => (
          <BooleanFieldLayout
            key={option.value}
            text={option.text}
            helpText={option.helpText}
            controlPosition={controlPosition}
            disabled={disabled || option.disabled}
          >
            {({
              id: fieldId,
              describedBy: optionDescribedBy,
              disabled: fieldDisabled,
            }) => (
              <CheckboxControl
                id={fieldId}
                disabled={fieldDisabled}
                aria-describedby={optionDescribedBy}
                checked={selected.includes(option.value)}
                onCheckedChange={(checked) => toggle(option.value, checked)}
              />
            )}
          </BooleanFieldLayout>
        ))}
      </div>
      {helpText && !error && <FieldMessage id={helpTextId}>{helpText}</FieldMessage>}
      {error && (
        <FieldMessage id={errorId} invalid role="alert">
          {error}
        </FieldMessage>
      )}
    </div>
  );
}

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

Options APINotification channels with four options and controlled value.

Browse the full examples gallery