CheckboxSelect

PreviousNext

A dropdown trigger styled like a text field that opens a panel of checkboxes, enabling multi-value selection.

Please select at least one priority
'use client';

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

const statusOptions = [
  { value: 'open', label: 'Open' },
  { value: 'fixed', label: 'Fixed' },
  { value: 'in-progress', label: 'In Progress' },
  { value: 'closed', label: 'Closed' },
];

export function CheckboxSelectDemo() {
  const [status, setStatus] = useState<string[]>(['open']);
  const [categories, setCategories] = useState<string[]>([]);

  return (
    <div className="space-y-24" style={{ minWidth: 300 }}>
      <CheckboxSelect
        label="Status"
        placeholder="Select statuses..."
        options={statusOptions}
        value={status}
        onChange={(_, v) => setStatus(v)}
      />

      <CheckboxSelect
        label="Category"
        placeholder="Select categories..."
        groups={[
          {
            label: 'Travel',
            options: [
              { value: 'flight', label: 'Flight' },
              { value: 'hotel', label: 'Hotel' },
            ],
          },
          {
            label: 'Activities',
            options: [
              { value: 'ski', label: 'Ski' },
              { value: 'golf', label: 'Golf' },
              { value: 'spa', label: 'Spa' },
            ],
          },
        ]}
        value={categories}
        onChange={(_, v) => setCategories(v)}
        renderValue={(vals) => `${vals.length} selected`}
      />

      <CheckboxSelect
        label="Priority"
        options={[
          { value: 'high', label: 'High' },
          { value: 'medium', label: 'Medium' },
          { value: 'low', label: 'Low' },
        ]}
        validationStatus="error"
        errorMessage="Please select at least one priority"
      />

      <CheckboxSelect label="Tags" options={statusOptions} value={['open']} disabled />
    </div>
  );
}

Installation

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

Usage

import { CheckboxSelect } from '@/ui/forms/CheckboxSelect';
 
export function Component() {
  return (
    <CheckboxSelect
      label="Status"
      options={[
        { value: 'open', label: 'Open' },
        { value: 'fixed', label: 'Fixed' },
      ]}
    />
  );
}

API Reference

CheckboxSelect

PropTypeDefaultDescription
labelReactNodeundefinedLabel displayed above the trigger
descriptionstringundefinedSecondary description shown next to the label
placeholderstring"Select..."Text shown in the trigger when no values are selected
optionsCheckboxSelectOption[]undefinedFlat list of options. Use groups instead for grouped options
groupsCheckboxSelectGroup[]undefinedGrouped options with optional group labels
valueValue[]undefinedControlled selected values
onChange(name: string, value: Value[]) => voidundefinedCalled with the updated selection when a checkbox is toggled
renderValue(selected: Value[]) => ReactNodeundefinedCustom renderer for the trigger label when values are selected
disabledbooleanfalseDisables the trigger and all checkboxes
requiredbooleanfalseMarks the field as required
validationStatus"default" | "error" | "success""default"Visual validation state of the trigger
errorMessagestringundefinedError text shown below when validationStatus is "error"
classNamestringundefinedAdditional CSS classes on the outer wrapper

CheckboxSelectOption

PropTypeDescription
valueValueThe option's value
labelReactNodeLabel shown in the panel

CheckboxSelectGroup

PropTypeDescription
labelReactNodeOptional group heading
optionsCheckboxSelectOption[]Options within this group

Notes

  • The dropdown closes when clicking outside the component.
  • Pass groups instead of options to render options under labeled sections.
  • Use renderValue to customize the summary shown in the trigger (e.g. "3 selected").
  • The trigger inherits the same border/pill styling as TextField and Select.