RHFCheckboxGroup

The RHFCheckboxGroup component renders multiple checkboxes, allowing users to select one or more items from a set. It supports both arrays and arrays of objects for options, and each checkbox can be customized as needed.

Usage

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

Example with an array of strings:

<RHFCheckboxGroup
  fieldName="toDo"
  control={control}
  label="Tasks to do"
  options={['Read Mails', 'Go for a hike', 'Bring groceries']}
/>

Example with an array of objects:

<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.

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