RHFCheckboxGroup

RHFCheckboxGroup renders a group of checkboxes from options and stores an array of the selected values in your form. It supports both primitive and object options through labelKey and valueKey.

Usage

import RHFCheckboxGroup, { RHFCheckboxGroupProps } from '@nish1896/rhf-mui-components/mui/checkbox-group';

import { useForm } from 'react-hook-form';

type FormValues = {
  permissions: string[];
};

const permissionOptions = ['Read', 'Write', 'Delete'];

const { control, handleSubmit } = useForm<FormValues>({
  defaultValues: { permissions: [] }
});

<form onSubmit={handleSubmit(values => console.log(values))}>
  <RHFCheckboxGroup
    fieldName="permissions"
    control={control}
    label="Permissions"
    options={permissionOptions}
    registerOptions={{
      validate: value => value.length > 0 || 'Select at least one permission'
    }}
  />
</form>

The stored value is an array of the checked options' values, in the order they were checked. onValueChange receives { newValue, toggledValue, checked, event }: the next array, the value of the checkbox that was toggled, its new checked state, and the change event.

Option value types

The type of the options is preserved. A checkbox's value is a string in the DOM, but the component converts it back to the type of the option, so string options give a string[] and number options give a number[].

Declare primitive options outside the JSX, as below. An array written inline is inferred by TypeScript as a union of its literal values, such as 1 | 2 | 3 | 4, and then a number[] form value doesn't match it.

const roomOptions = [1, 2, 3, 4];

const { control } = useForm<{ rooms: number[] }>({
  defaultValues: { rooms: [] }
});

<RHFCheckboxGroup
  fieldName="rooms"
  control={control}
  label="Rooms"
  options={roomOptions}
/>

With an array of objects

Options can also be objects. Both labelKey and valueKey are required in this case. labelKey is the property used as each checkbox's label, and valueKey is the property used as its value. The stored value is an array of the valueKey properties of the checked options, not the whole objects, and it keeps the type of that property.

<RHFCheckboxGroup
  fieldName="countries"
  control={control}
  label="Select countries you've visited"
  options={[
    { code: 'AUS', country: 'Australia' },
    { code: 'IN', country: 'India' },
    { code: 'UAE', country: 'United Arab Emirates' }
  ]}
  labelKey="country"
  valueKey="code"
/>

Warning

When using an array of objects for options, both labelKey and valueKey are required. If either is missing, an error will be thrown.

Customizing individual options

renderOptionLabel replaces the label of each checkbox. It receives the option and a state object with disabled, which is true when the option or the whole group is disabled, and selected, which is true while the checkbox is checked. The label can be any ReactNode.

getOptionDisabled receives an option and returns true to disable that checkbox. A disabled checkbox keeps its current state, so a disabled option that is already checked stays in the stored value. disabled on the group disables every option at once.

<RHFCheckboxGroup
  fieldName="addons"
  control={control}
  label="Add-ons"
  options={[
    { id: 'wifi', name: 'Wi-Fi', soldOut: false },
    { id: 'parking', name: 'Parking', soldOut: true },
    { id: 'breakfast', name: 'Breakfast', soldOut: false }
  ]}
  labelKey="name"
  valueKey="id"
  getOptionDisabled={option => option.soldOut}
  renderOptionLabel={(option, { disabled, selected }) => (
    <span
      style={{
        opacity: disabled ? 0.5 : 1,
        fontWeight: selected ? 700 : 400
      }}
    >
      {option.name}{disabled ? ' (unavailable)' : ''}
    </span>
  )}
/>

Styling each checkbox

checkboxProps is forwarded to every Checkbox, for example a color, size or custom icon and checkedIcon. formControlLabelProps is forwarded to every FormControlLabel that wraps a checkbox and its label, for example labelPlacement. Its sx is merged with the default FormControlLabel styles from ConfigProvider.

import CircleOutlinedIcon from '@mui/icons-material/CircleOutlined';
import CheckCircleIcon from '@mui/icons-material/CheckCircle';

<RHFCheckboxGroup
  fieldName="permissions"
  control={control}
  options={permissionOptions}
  checkboxProps={{
    color: 'secondary',
    size: 'small',
    icon: <CircleOutlinedIcon />,
    checkedIcon: <CheckCircleIcon />
  }}
  formControlLabelProps={{
    labelPlacement: 'start',
    sx: { justifyContent: 'space-between', mx: 0 }
  }}
/>

Handling value changes

onValueChange runs after the new array has been stored in the form. It receives { newValue, toggledValue, checked, event }: the next array, the value of the checkbox that was toggled, its new checked state, and the change event.

<RHFCheckboxGroup
  fieldName="permissions"
  control={control}
  options={['Read', 'Write', 'Delete']}
  onValueChange={({ newValue, toggledValue, checked, event }) => {
    console.log(toggledValue, checked ? 'checked' : 'unchecked');
  }}
/>

Use customOnChange when you need to change what gets stored. It replaces the default handling, so you must call rhfOnChange yourself with the array to store. It receives { rhfOnChange, currentValue, toggledValue, checked, event }, where currentValue is the array before the toggle. This example makes "None" exclusive: onValueChange is not called when customOnChange is used.

<RHFCheckboxGroup
  fieldName="allergies"
  control={control}
  options={['Peanuts', 'Gluten', 'Dairy', 'None']}
  customOnChange={({ rhfOnChange, currentValue, toggledValue, checked, event }) => {
    if (checked && toggledValue === 'None') {
      rhfOnChange(['None']);
    } else if (checked) {
      rhfOnChange([...currentValue.filter(value => value !== 'None'), toggledValue]);
    } else {
      rhfOnChange(currentValue.filter(value => value !== toggledValue));
    }
  }}
/>

The label, helper text and error props work as described in RHFTextField.

Examples

API

RHFCheckboxGroupProps accepts the following props. Props marked with * are required.

Name	Type	Description
`fieldName`*	`string`	Name of the field registered with React Hook Form. This prop is required for all components.
`control`*	UseFormControl	The control option yielded on calling the useForm hook.
`registerOptions`	`RegisterOptions`	React Hook Form validation rules. Useful when not using a schema validation library such as Yup or Joi.
`options`*	`string[] / object[]`	An array with string or object values. Make sure to pass `labelKey` and `valueKey` when options is an array of objects.
`labelKey`	`string`	Property name used as the visible label for each option. Required when `options` is an array of objects.
`valueKey`	`string`	Property name used as the stored value for each option. Required when `options` is an array of objects.
`customOnChange`	`({ rhfOnChange, event, currentValue, toggledValue, checked }) => void`	Callback function that allows custom logic to be executed whenever a checkbox value changes. You can use this to implement conditional selection, logging, or side effects before or after updating the form value.
`onValueChange`	`({ event, newValue, toggledValue, checked }) => void`	An optional callback function triggered upon selection. The `toggledValue` parameter provides the value of the item being checked, while the `newValue` parameter returns the updated complete value of the form field.
`disabled`	`boolean`	Disables the component and prevents user interaction.
`renderOptionLabel`	`(option) => ReactNode`	Custom renderer for option labels. When not provided, the label is derived from the option value or the property specified by `labelKey`. Option state param added in `v4.2.0`
`getOptionDisabled`	`(option) => boolean`	Function used to determine whether an option should be disabled. Return `true` to disable the option and prevent it from being selected.
`label`	`ReactNode`	The text to render in the FormLabel component. By default, the value of `fieldName` is transformed (e.g., "firstName" to "First Name") using the fieldNameToLabel function.
`showLabelAboveFormField`	`boolean`	Renders the form label above the field.
`formLabelProps`	FormLabelProps	FormLabelProps to customise FormLabel component for a field. Multiple fields can be configured using the ConfigProvider component.
`checkboxProps`	CheckboxProps	Checkbox Props to customise each checkbox in checkbox group.
`formControlLabelProps`	FormControlLabelProps	FormControlLabelProps to customise `FormControlLabel` component for a field. Multiple fields can be configured using the ConfigProvider component.
`hideLabel`	`boolean`	Hides the FormLabel component if you don’t want to display the default form label component or prefer to render a fully custom label instead.
`required`	`boolean`	Indicates that the field is mandatory by adding an asterisk symbol (*) to the `formLabel`. This visual cue helps users quickly identify required fields in the form.
`renderError`	`(error: FieldError) => ReactNode`	Custom renderer for the React Hook Form field error. Receives the current field error and returns the content to display, such as `error.message` or a custom React element in the `HelperText` component. Added in `v4.1.0`.
`hideErrorMessage`	`boolean`	A flag to prevent replacement of helper text of a field by the `errorMessage` when the validation is triggered.
`helperText`	`ReactNode`	The content to display within the FormHelperText component below the field. If the field validation fails, this content will be overridden by the corresponding error message.
`formHelperTextProps`	FormHelperTextProps	FormHelperTextProps to customise FormHelperText component for a field. Multiple fields can be configured using the ConfigProvider component.
`customIds`	`{ field, label, helperText, error }`	Overrides the default field, label, helper text, and error IDs used for accessibility.

Source Code

View the full implementation of this component on GitHub.

Checkbox

Radio Group