RHFCheckbox

RHFCheckbox is a single Checkbox with a boolean value, an inline label, and optional helper text or error state, bound to React Hook Form through control.

For choosing several items from a list, use RHFCheckboxGroup.

Usage

import RHFCheckbox, { RHFCheckboxProps } from '@nish1896/rhf-mui-components/mui/checkbox';

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

type FormValues = {
  terms: boolean;
};

const { control, handleSubmit } = useForm<FormValues>({
  defaultValues: { terms: false }
});

<form onSubmit={handleSubmit(values => console.log(values))}>
  <RHFCheckbox
    fieldName="terms"
    control={control}
    label="I accept the terms and conditions"
  />
</form>

The stored value is a boolean. onValueChange receives { newValue, event }: the next checked state and the change event. The label defaults to text generated from fieldName, so terms becomes "Terms", and hideLabel removes the visible label.

Label and placement

label accepts any ReactNode, so it can hold a link, such as one to the terms. The label sits after the checkbox by default. formControlLabelProps is forwarded to the FormControlLabel around the checkbox, so labelPlacement can move it to the 'start', 'top' or 'bottom'. Its sx is merged with the default FormControlLabel styles from ConfigProvider. The component controls the FormControlLabel's control, label and disabled.

<RHFCheckbox
  fieldName="terms"
  control={control}
  label={<>I accept the <a href="/terms">terms and conditions</a></>}
  formControlLabelProps={{
    labelPlacement: 'start',
    sx: { justifyContent: 'space-between', ml: 0 }
  }}
/>

Styling the checkbox

The remaining CheckboxProps are passed to the Checkbox, for example color, size, sx, and custom icon and checkedIcon. slotProps is forwarded too. The checkbox's id, name, checked and onChange are managed by the component.

import FavoriteBorderIcon from '@mui/icons-material/FavoriteBorder';
import FavoriteIcon from '@mui/icons-material/Favorite';

<RHFCheckbox
  fieldName="favourite"
  control={control}
  color="error"
  size="small"
  icon={<FavoriteBorderIcon />}
  checkedIcon={<FavoriteIcon />}
/>

The indeterminate prop shows the dash icon, which is useful for a "select all" box that controls other checkboxes. It only changes how the checkbox looks, and the stored value still decides whether it is checked.

Required, helper text and errors

A required rule fails while the checkbox is unchecked, which makes it a simple way to enforce accepting terms. The message is shown below the checkbox and replaces helperText while it is visible.

<RHFCheckbox
  fieldName="terms"
  control={control}
  label="I accept the terms and conditions"
  helperText="Required to continue"
  registerOptions={{ required: 'You must accept the terms' }}
/>

Handling value changes

onValueChange runs after the new value has been stored in the form. It receives { newValue, event }:

<RHFCheckbox
  fieldName="newsletter"
  control={control}
  onValueChange={({ newValue, event }) => {
    if (!newValue) {
      setValue('newsletterFrequency', '');
    }
  }}
/>

Use customOnChange when you need to change what gets stored. It replaces the default handling, so you must call rhfOnChange yourself with the value to store. This example only allows checking the box once terms were opened: onValueChange is not called when customOnChange is used.

<RHFCheckbox
  fieldName="terms"
  control={control}
  customOnChange={({ rhfOnChange, newValue, event }) => {
    if (!newValue || hasOpenedTerms) {
      rhfOnChange(newValue);
    }
  }}
/>

Examples

API

RHFCheckboxProps extends CheckboxProps and accepts the following additional 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.
`customOnChange`	`({ rhfOnChange, newValue, event }) => void`	Override the default `onChange` behavior of the component. You can also prevent the toggle behaviour using `event.preventDefault()` based on your business logic, but must pass the updated `newValue` value to the rhfOnChange function to toggle the field.
`onValueChange`	`({ newValue, event }) => void`	An optional callback function which returns the state of the checkbox.
`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.
`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.
`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.

Multi Autocomplete Object

Checkbox Group