Migrating from v4 to v5

@nish1896/rhf-mui-components v5 targets Material UI v9 and MUI X Date Pickers v9.

v4 targeted MUI v6/v7 and MUI X Date Pickers v7/v8.

TL;DR

1. Upgrade your MUI packages to v9.
2. Upgrade @nish1896/rhf-mui-components to v5.
3. Refer to the MUI v9 and MUI X Pickers v9 migration guides.
4. Run MUI's official codemods over your own code.
5. Remove any remaining errorMessage prop — see errorMessage removed.
6. Fix the pass-through props listed in What you need to change.

1. Update dependencies

npm install @mui/material@^9 @mui/icons-material@^9 @mui/x-date-pickers@^9 @nish1896/rhf-mui-components@^5

yarn add @mui/material@^9 @mui/icons-material@^9 @mui/x-date-pickers@^9 @nish1896/rhf-mui-components@^5

pnpm add @mui/material@^9 @mui/icons-material@^9 @mui/x-date-pickers@^9 @nish1896/rhf-mui-components@^5

peerDependencies are now ^9.0.0 for all MUI packages, so your package manager will warn if any of them is still on an older version.

2. Run MUI's codemods

Most of the work is in your own app code, and MUI ships codemods for it. There is no single all-in-one preset for v9 — the codemods are per-concern:

# Rewrites removed system props into `sx` (Box, Stack, Grid, Typography, Link, …)
npx @mui/codemod@latest v9.0.0/system-props <path>

# Optionally narrow it to specific components
npx @mui/codemod@latest v9.0.0/system-props <path> -- --jsx=Box,Typography

# Per-component deprecations, e.g. the slot migrations
npx @mui/codemod@latest deprecations/<component-name> <path>

The codemods do not cover the pass-through props documented below, because those are nested inside our component props (textFieldProps, checkboxProps, slotProps.textField) rather than applied directly to a MUI element — fix those by hand.

Then read MUI's own guides, which cover everything outside this package:

• Upgrade to Material UI v9
• Upgrade to MUI X v9

3. What you need to change

errorMessage removed

The errorMessage prop — deprecated back in v4 — has been removed from every component in v5. Field errors are now derived internally from React Hook Form's own field state, so there's nothing left to pass through manually.

  <RHFTextField
    fieldName="email"
    control={control}
    registerOptions={{ required: 'Email is required' }}
-   errorMessage={errors?.email?.message}
  />

If you need to customize how an error renders (not just supply the message), use the renderError prop instead.

Anything forwarded to a TextField

MUI v9 removed TextField's legacy prop bag in favour of slotProps. In this package that surfaces in three places:

  <RHFAutocomplete
    fieldName="country"
    control={control}
    options={options}
    textFieldProps={{
-     InputProps: { startAdornment: <SearchIcon /> },
-     inputProps: { maxLength: 32 },
-     InputLabelProps: { shrink: true },
-     FormHelperTextProps: { sx: { fontStyle: 'italic' } },
+     slotProps: {
+       input: { startAdornment: <SearchIcon /> },
+       htmlInput: { maxLength: 32 },
+       inputLabel: { shrink: true },
+       formHelperText: { sx: { fontStyle: 'italic' } },
+     },
    }}
  />

The same rename applies when the props are set directly on a component:

  <RHFPhoneInput
    fieldName="phone"
    control={control}
-   inputProps={{ maxLength: 20 }}
+   slotProps={{ htmlInput: { maxLength: 20 } }}
  />

checkboxProps / radioProps, and RHFSwitch

MUI v9 removed inputProps and inputRef from SwitchBase, the shared base of Checkbox, Radio and Switch.

Affects RHFCheckbox, RHFCheckboxGroup, RHFRadioGroup, RHFSwitch, RHFMultiAutocomplete, RHFMultiAutocompleteObject.

  <RHFCheckboxGroup
    fieldName="topics"
    control={control}
    options={options}
    checkboxProps={{
-     inputProps: { 'aria-describedby': 'topics-hint' },
-     inputRef: ref,
+     slotProps: { input: { 'aria-describedby': 'topics-hint', ref } },
    }}
  />

Date / Time picker slotProps.textField

The picker text field moved to the same slot model.

Affects all RHFDatePicker, RHFTimePicker and RHFDateTimePicker variants (responsive, desktop, mobile, static).

  <RHFDatePicker
    fieldName="dob"
    control={control}
    slotProps={{
      textField: {
-       inputProps: { placeholder: 'DD/MM/YYYY' },
+       slotProps: { htmlInput: { placeholder: 'DD/MM/YYYY' } },
      },
    }}
  />

This one fails silently — the old inputProps is simply ignored rather than raising a type error in every configuration, so attributes disappear with no warning. Grep your codebase for textField + inputProps explicitly.

System props are gone — use sx

MUI v9 removed system props from Box, Stack, Grid, Typography, Link and DialogContentText. Any prop bag we forward to those (formLabelProps, formHelperTextProps, formControlLabelProps, ChipProps) is affected.

- <Typography marginRight="8px" color="gray">
+ <Typography sx={{ marginRight: '8px', color: 'gray' }}>

  <RHFTextField
    fieldName="email"
    control={control}
-   formLabelProps={{ fontWeight: 600 }}
+   formLabelProps={{ sx: { fontWeight: 600 } }}
  />

renderOptionLabel and custom option renderers

If your renderer returns MUI components using system props, apply the same sx change. The renderOptionLabel(option, state) signature itself is unchanged.

Icons: *Outline → *Outlined

MUI v9 deleted 23 legacy *Outline icon aliases.

- import ErrorOutlineIcon from '@mui/icons-material/ErrorOutline';
+ import ErrorOutlineIcon from '@mui/icons-material/ErrorOutlined';

RHFSlider: onMouseDown → onPointerDown

v9's Slider uses pointer events. If you passed onMouseDown to cancel a drag, it no longer fires.

<RHFSlider fieldName="volume" control={control}
- onMouseDown={e => e.preventDefault()}
+ onPointerDown={e => e.preventDefault()}
/>

Theme: MuiAlert style overrides

v9 collapsed the per-severity standard{Info,Success,Warning,Error} slots into a single standard slot, with severity moved onto separate colorInfo/colorSuccess/… classes.

  MuiAlert: {
    styleOverrides: {
-     standardInfo: { backgroundColor: '…' },
-     standardSuccess: { backgroundColor: '…' },
+     standard: ({ ownerState }) => ({
+       ...(ownerState.severity === 'info' && { backgroundColor: '…' }),
+       ...(ownerState.severity === 'success' && { backgroundColor: '…' }),
+     }),
    },
  },

GridLegacy removed

If your layout still used the legacy Grid API, update to the new Grid sizing:

- <Grid item xs={12} md={6}>
+ <Grid size={{ xs: 12, md: 6 }}>

What did not change

• Every component's own props — fieldName, control, registerOptions, onValueChange, renderError, helperText, label, hideLabel, showLabelAboveFormField, customIds, labelKey/valueKey, getOptionDisabled, ChipProps, limitTags, …
• ConfigProvider and every config option.
• form-helpers exports (fieldNameToId, fieldNameToLabel, getFileSize, validateFileList, colorToString).
• ref forwarding on the Autocomplete family and the pickers.
• RHFSelect / RHFNativeSelect inputProps — MUI's Select kept this prop in v9.