CheckboxGroupField

CheckboxGroupField renders a list of checkbox options allowing the user to select one or more values. A custom render function can replace the default checkbox + label layout with any React node.

Props

| Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | options | CheckboxOption[] | Yes | — | Array of options to display (see CheckboxOption shape below). | | selectedValues | (string \| number \| boolean)[] | Yes | — | Array of currently selected values. | | onChange | (values: (string \| number \| boolean)[]) => void | Yes | — | Called with the updated selected-values array when any option is toggled. | | label | string | No | — | Label rendered above the group. | | description | string | No | — | Helper text rendered below the label. | | renderOption | (option: CheckboxOption, index: number, isChecked: boolean) => React.ReactNode | No | — | Custom render function for each option. When provided, the default checkbox layout is replaced. | | containerStyle | React.CSSProperties | No | — | Styles applied to the root container. | | labelStyle | React.CSSProperties | No | — | Styles applied to the group label. | | descriptionStyle | React.CSSProperties | No | — | Styles applied to the description paragraph. | | optionContainerStyle | React.CSSProperties | No | — | Styles applied to each option's row container (default layout only). | | optionLabelStyle | React.CSSProperties | No | — | Styles applied to each option's label span (default layout only). | | className | string | No | — | CSS class name applied to the root container. | | id | string | No | — | id attribute on the root container. |

CheckboxOption shape

interface CheckboxOption {
  label: string;
  value: string | number | boolean;
}

Usage

Basic

import React, { useState } from 'react';
import CheckboxGroupField from '@/components/fields/CheckboxGroupField';

const options = [
  { label: 'Email', value: 'email' },
  { label: 'SMS', value: 'sms' },
  { label: 'Push notification', value: 'push' },
];

export default function Example() {
  const [selected, setSelected] = useState<string[]>([]);

  return (
    <CheckboxGroupField
      label="Notification channels"
      options={options}
      selectedValues={selected}
      onChange={(vals) => setSelected(vals as string[])}
    />
  );
}

With custom option renderer

<CheckboxGroupField
  label="Permissions"
  options={permissionOptions}
  selectedValues={selected}
  onChange={setSelected}
  renderOption={(option, _index, isChecked) => (
    <div style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
      <span style={{ fontSize: 20 }}>{isChecked ? '✅' : '⬜'}</span>
      <span>{option.label}</span>
    </div>
  )}
/>