RHFRating

RHFRating wraps the Material UI Rating star input and binds it to React Hook Form. The stored value is a number, or null when the rating is cleared.

Usage

import RHFRating, { RHFRatingProps } from '@nish1896/rhf-mui-components/mui/rating';

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

type FormValues = {
  score: number | null;
};

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

<form onSubmit={handleSubmit(values => console.log(values))}>
  <RHFRating
    fieldName="score"
    control={control}
    registerOptions={{ required: 'Please leave a rating' }}
  />
</form>

onValueChange receives { newValue, event }, and newValue is null when the user clears the rating by clicking the selected star again.

Number of stars and precision

The remaining RatingProps are passed through. max sets how many stars are shown, which is 5 by default, precision sets the smallest step that can be chosen, and size scales the stars. Use precision={0.5} to allow half stars.

<RHFRating
  fieldName="score"
  control={control}
  max={10}
  precision={0.5}
  size="large"
/>

Custom icons

icon replaces the filled icon, and emptyIcon replaces the empty one. Give the icons fontSize="inherit" so that size still applies.

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

<RHFRating
  fieldName="love"
  control={control}
  icon={<FavoriteIcon fontSize="inherit" />}
  emptyIcon={<FavoriteBorderIcon fontSize="inherit" />}
  sx={{ color: 'error.main' }}
/>

Read-only and disabled

readOnly shows a rating that the user can't change, which suits displaying an average. disabled dims the control and blocks input, and a form-level disabled on useForm is respected too.

<RHFRating
  fieldName="average"
  control={control}
  precision={0.5}
  readOnly
/>

Label placement

A rating has no inline label, so showLabelAboveFormField defaults to true and the label is shown above the stars. Pass false to hide the visible label. The error, helper text and change props work as described in RHFTextField.

Handling value changes

onValueChange runs after the new value has been stored in the form. It receives { newValue, event }, where newValue is null when the user clears the rating:

<RHFRating
  fieldName="score"
  control={control}
  onValueChange={({ newValue, event }) => trackRating(newValue)}
/>

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 doesn't allow clearing the rating: onValueChange is not called when customOnChange is used.

<RHFRating
  fieldName="score"
  control={control}
  customOnChange={({ rhfOnChange, newValue, event }) => {
    if (newValue !== null) {
      rhfOnChange(newValue);
    }
  }}
/>

Examples

API

RHFRatingProps extends RatingProps 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.
`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.
`customOnChange`	`({ rhfOnChange, newValue, event }) => void`	Overrides the default `onChange` behavior of the Rating component, allowing you to enforce a minimum rating value and prevent users from selecting a value below the defined threshold.
`onValueChange`	`({ newValue, event }) => void`	Callback function triggered when the rating value changes.
`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.
`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.

Switch

Date Picker