9.x → 10.x migration guide
Migrate with LLM agents
LLM agents can perform the migration for you. Copy the link to the md version of this page and ask your AI agent to apply it: it includes all breaking changes and migration steps.
Migrate with LLMRelease notes
This guide covers only breaking changes. New features and improvements are listed in the 10.0 changelog:
View 10.0 release notesPrerequisites
Mantine 10.x requires React 19.2 or later. The new colors require Chrome and Edge 111,
Safari 16.2 or Firefox 113 and later. To support older browsers, use the v9 opt-out
or a PostCSS plugin that converts oklch values.
Update dependencies
Update all @mantine/* packages to version 9.8.2.
If you use @mantine/charts, update recharts to 3.11.0 or later.
Changes to review by human
This section is meant for human review. Compare each demo with your application and decide whether to keep the new look or restore the previous one. Everything that can be migrated mechanically is in Changes for automated migration.
New OKLCH default palettes
Default colors were regenerated in the OKLCH color space. Color names and the number of shades are the same, color values are different. Review custom colors that were picked to match the old defaults. If you cannot migrate now, use the v9 opt-out.
The default dark primaryShade is now 7 instead of 8. To keep the 9.x shade, set
primaryShade: { light: 6, dark: 8 } in the theme.
--mantine-color-* CSS variables now contain oklch() strings. Update code that parses them
as hex or passes them to APIs without oklch support, for example canvas.
autoContrast is enabled by default
Check filled components with light backgrounds: their text may now be black instead of white. To restore the 9.x behavior, disable autoContrast in your theme:
Darker dark theme
The dark color scheme is darker than in 9.x: the page is dark-8 and panels are dark-7.
If your styles use dark-N backgrounds, shift the index by one or use the semantic variables below.
Focus rings use the --mantine-color-focus-ring variable instead of the primary color.
If you override the focus ring color, override this variable.
Inputs, checkboxes, radios, Dropzone and RichTextEditor use the page color as background
instead of the panel color. To keep the 9.x input background, set the input surface:
New semantic color variables
Components use semantic variables such as --mantine-color-border instead of gray-N and
dark-N shades. Palette overrides keep working. To change the colors of all components at
once, override the semantic variables, see the colors guide:
Paper is deprecated, use Surface
Replace Paper with Surface, it supports the same props. Paper will be
removed in 11.0. In dark color scheme nested surfaces step up one level per nesting, set
autoDepth={false} on the nested Surface to keep the Paper look:
Level 0 – surface-page
Level 1 – surface-panel
Level 2 – surface-panel-2
Disabled state
Disabled components keep their colors and are displayed with reduced opacity instead of turning gray. The v9 opt-out does not restore the gray styles:
Set theme.disabledOpacity to change the opacity:
Replace the --mantine-color-disabled-* variables and the disabledBody, disabledText and
disabledBorder keys of vars.colors in @mantine/vanilla-extract with the opacity variable:
Blockquote look
Blockquote no longer has a background and rounded corners, the icon is displayed above the quote and is smaller:
Life is like an npm install – you never know what you are going to get.– Forrest Gump
The radius prop and the --bq-bg-light, --bq-bg-dark and --bq-radius variables were
removed. To restore the previous look, style the root element:
Slider thumb
Slider and RangeSlider thumb is white with a colored border, and its size
depends on the size prop. Set variant="filled" to fill the thumb with the slider color and
thumbSize to restore the previous size. Check custom thumb styles:
ColorPicker swatches
ColorPicker and ColorInput display 10 swatches per row instead of 7 and follow
theme.defaultRadius. Set swatchesPerRow={7} and radius to restore the previous layout:
Calendars have 6 weeks in every month
Every month has 6 weeks in all calendar components, so the calendar height does not change
between months. Set consistentWeeks: false in DatesProvider settings to restore the
previous behavior:
consistentWeeks: true (default)| Mo | Tu | We | Th | Fr | Sa | Su |
|---|---|---|---|---|---|---|
consistentWeeks: false| Mo | Tu | We | Th | Fr | Sa | Su |
|---|---|---|---|---|---|---|
DateTimePicker submit button
DateTimePicker and InlineDateTimePicker submit button is a default variant Button
with a text label instead of a filled icon button. Set submitButtonLabel on the component
or in DatesProvider settings to change the label, and submitButtonProps to change the variant:
Other layout changes
Grid.Colwithoutspanspans allcolumnsof the grid instead of 12. Setspan={12}to keep the old width in grids with a customcolumnsvalue.DataListlabelWidthsets a fixed width of the label column instead of its minimum width, so long labels wrap. If your labels now wrap, increaselabelWidth.
Picker inputs open in a drawer on mobile
Picker inputs and DateTimePicker open in a bottom drawer on small screens, and onChange
is called only when the user presses the submit button in the drawer. The first input in the
demo opens the drawer on every screen size:
Set dropdownType="popover" to keep the popover on all screens and applyOnSubmit={false}
to call onChange on selection. Both props can be set for all components in the theme:
Drawer swipe to dismiss
Drawer is closed with a swipe gesture by default. Set the
data-drawer-no-swipe attribute on draggable elements inside the drawer to keep the gesture
away from them:
To disable the gesture, set withSwipe={false} on Drawer or in the theme:
Tooltip opens on focus
Tooltip opens when the target receives keyboard focus, press Tab to focus the button in the
demo. To restore the previous behavior, set events={{ hover: true, focus: false, touch: false }}:
Uncontrolled form mode is the default
useForm and useField are uncontrolled by default: the form component does not rerender
when the user types. The automated migration replaces
form.values, form.isDirty() and form.isTouched() reads during render with hooks.
To keep the 9.x behavior instead, set mode: 'controlled' in every useForm call:
See form modes for the differences between the two modes.
MaskInput stores raw values
MaskInput value and onChange work with the raw value without the mask. If your application
stores masked values, for example (123) 456-7890, convert them with unformatMask when
loading or migrate the stored data:
v9 opt-out
If your application cannot be migrated now, restore 9.x colors with v9Theme and
v9CssVariablesResolver. Both will be removed in 11.0:
Nested popover dismissal
Remove withinPortal={false} if you used it only to keep a parent popover open.
Keep it if the dropdown should render next to its target in the DOM.
Escape now dismisses the inner dropdown first. Set escapeKeyBubbles on the inner popover to dismiss its ancestors too.
To restore 9.x dismissal throughout your application, set dismissMode in your theme:
Changes for automated migration
This part is written for coding agents. Each entry names the 9.x usage to search for and the replacement. Apply every entry that matches the codebase, run the type checker and tests afterwards, and report behavior changes from this list that cannot be resolved by a code change.
Stepper.Step step, state, allowStepClick and onClick props
Remove step, state, allowStepClick and onClick props from Stepper.Step elements.
Stepper ignored them in 9.x and applies them in 10.x, so a step with step={5} displays 6
as its icon and ignores the active prop. Keep them only on steps that intentionally do not
follow the active prop of Stepper.
Timeline data-opposite attribute
Timeline no longer sets data-opposite on the root element. Replace selectors that target it:
Controller hook types renamed
Rename the imported types of useTimer, useEditable and useImageCropper hooks.
The useHook.Options and useHook.ReturnValue namespace types were removed as well,
replace them with the same types:
Controller hooks return a memoized object
useTimer, useEditable, useImageCropper and usePagination return the same object until
the state changes. Replace useEffect dependencies on the returned object with the state
values the effect reads:
Tree store prop
Rename the tree prop of Tree to store, the tree field of the renderNode payload to
store, and the TreeController type to TreeStore:
Combobox store listId and selectedOptionIndex
Replace combobox.listId with combobox.getListId() and combobox.selectedOptionIndex with
combobox.getSelectedOptionIndex(). useVirtualizedCombobox still accepts the
selectedOptionIndex option.
comboboxProps.store in Select, MultiSelect, TagsInput and Autocomplete
store passed in comboboxProps is ignored. Create the store with the component hook and pass
it to the store prop. The hook returns all useCombobox actions:
Combobox.Target role and aria-expanded
Combobox.Target sets role="combobox" and aria-expanded on the target element by default.
Tests that query the target with getByRole('textbox') must query getByRole('combobox')
instead. Set withExpandedAttribute={false} on Combobox.Target to restore the 9.x markup.
Combobox limit counts options across groups
In Select, MultiSelect, Autocomplete and TagsInput with grouped data, limit now counts
options across all groups. In 9.x, every group counted towards the limit as one item. Reduce
limit if the dropdown displays more options than expected.
Pagination root element
Pagination root element is a nav landmark. Remove nav wrappers around Pagination to
avoid nested landmarks. Tests that query role="navigation" now match the pagination root.
NavLink with nested links
NavLink with children and without href is rendered as a button instead of an a element.
Update tests and styles that select the parent link by tag. Set component="a" to keep the 9.x element.
Portal shared node
Portal ignores className, style and id when the shared portal node or target is used.
To keep these props, set reuseTargetNode={false} on that Portal.
Modal and Drawer returnFocus without trapFocus
Modal and Drawer return focus to the previously focused element on close even with
trapFocus={false}. Set returnFocus={false} where focus must stay where it is.
ModalBase components removed
Replace ModalBase* components with Modal or Drawer
compound components:
Spotlight store registerAction and empty
registerAction function and the empty field of the Spotlight store were removed. Remove
calls to registerAction and reads of empty. Spotlight renders Spotlight.Empty with the
nothingFound content itself when no actions match the query.
RichTextEditor edit-link event
RichTextEditor.Link control listens to the edit-link event on the editor instead of
window. Replace window.dispatchEvent(new CustomEvent('edit-link')) with
(editor as any).emit('edit-link'), the event is not part of the tiptap EditorEvents type.
useMask and MaskInput separate option
Remove the separate option from useMask and the separate prop from MaskInput, they no
longer exist.
MaskInput value format
MaskInput value, defaultValue and onChange work with the raw value without the mask,
and onChange receives a string instead of an event. Replace event.currentTarget.value reads
in onChange handlers with the string argument. Masked strings are no longer parsed: value,
defaultValue and use-form values (initialValues, form.setFieldValue, form.reset) must be
raw. Convert stored masked values with unformatMask. useMask setValue accepts a raw value
as well. Use onChangeRaw to read the masked value.
beforeMaskedStateChange removed
Remove the beforeMaskedStateChange option from useMask and the prop from MaskInput. It
was never called. The MaskState type is no longer exported, remove its imports.
PinInput value with empty inputs
An empty PinInput input is a space in the value, so clearing one input no longer shifts the
others. Replace value.length checks that detect a complete value with isComplete() from
usePinInput or a regex:
TimeInput data-empty attribute
TimeInput sets data-empty on the input element while it has no value. Rename a custom
data-empty attribute passed to TimeInput.
RollingNumber root element
RollingNumber renders a span root element instead of a div. Change ref types from
HTMLDivElement to HTMLSpanElement.
Cascader data-active attribute
Rename [data-active] selectors on Cascader column options to [data-current]. In tests,
aria-selected on column options marks the selected value, not the option highlighted with
the keyboard. Query [data-current] to find the highlighted option.
Picker inputs calendar theme defaults
defaultLevel and defaultDate set in theme defaultProps of Calendar or a picker component
no longer apply to the dropdown of picker inputs. Add them to the defaultProps of the picker
input:
Picker inputs popoverProps.opened
popoverProps.opened on picker inputs and DateTimePicker requires popoverProps.onChange.
It is called on every open and close, and the input cannot open its dropdown without it:
With the controller prop, pass dropdownOpened and onDropdownOpenedChange to the controller
hook instead, popoverProps.opened is ignored.
DateTimePicker submitButtonProps
The submit button of DateTimePicker and InlineDateTimePicker is a Button instead of an
ActionIcon. Remove ActionIcon specific props from submitButtonProps, for example
size="input-sm".
DatesProvider consistentWeeks
consistentWeeks is true by default. Remove consistentWeeks: true from DatesProvider
settings.
useMatches options argument
Remove the second argument of useMatches. The hook always returns the base value on the
server and during hydration:
useScroller dragHandlers
dragHandlers returned from useScroller contains only onMouseDown. If the handlers are
passed one by one, keep onMouseDown and remove onMouseMove, onMouseUp and onMouseLeave.
Spreading {...dragHandlers} works as before. The hook no longer sets the cursor on the
container, use the isDragging value to set it.
useClickOutside handler event
The useClickOutside handler receives a FocusEvent when the user clicks inside an iframe.
If the handler argument is typed as MouseEvent | TouchEvent, add FocusEvent to the type:
SunburstChart endAngle
SunburstChart endAngle is the angle at which the chart ends, as in PieChart. In 9.x the
chart ended at startAngle + endAngle. If both props are set, pass the sum as endAngle.
Setting only startAngle still draws a full circle:
Move startAngle, endAngle and innerRadius from sunburstChartProps to the component
props. textOptions in sunburstChartProps is ignored because labels are drawn by Mantine.
@mantine/schedule changes
isAfterMinDateandisBeforeMaxDateare no longer exported. Compare dates withdayjsinstead.ScheduleHeader.varsResolverand theScheduleHeaderCssVariablestype are removed. The header has no CSS variables.- The
data-all-day-draggingattribute is removed fromWeekView. Usedata-event-interactionto style the view while an event is dragged. WeekViewandResourcesWeekViewweekLabelFormatdefaults toMMM Dinstead ofMMM DD. SetweekLabelFormat="MMM DD"to keep zero-padded days.MobileMonthViewcallsonDateChangewhen a day is selected. Ifdateis controlled, update it inonDateChange.WeekViewhighlights today by default, like the other views. SethighlightToday={false}to turn it off.
form.key removed
Remove key={form.key('path')} from inputs. In lists, use a stable key stored in the list item,
for example a randomId(), not the field path. useField no longer returns key, remove
key={field.key} the same way. The Key type is no longer exported, remove its imports:
Form values read during render
In uncontrolled mode the component that calls useForm does not rerender when values change.
Replace reads during render with hooks, calls in event handlers and form.onSubmit do not change:
If the application keeps the 9.x behavior with mode: 'controlled', skip this entry.
Uncontrolled form inputs receive value
In uncontrolled mode getInputProps returns value and checked instead of defaultValue
and defaultChecked. Change custom inputs and enhanceGetInputProps functions that read
defaultValue to read value. Add an initial value for every field rendered with an input,
otherwise React warns about an input switching from uncontrolled to controlled.
If a custom input keeps state that value cannot express, for example a partially entered
date, clear it with the use-form-field hook when the
form writes the value.
Form values are not cloned on every change
The object returned from form.getValues() and form.values is no longer a copy. Replace
mutations of it with form.setFieldValue or form.setValues.
form.setValues clears only errors of changed fields
form.setValues clears errors only of the fields it sets. Where all errors must disappear,
for example after a failed submit, call form.clearErrors() before it:
UseFieldReturnType type parameters
Remove the third type argument of UseFieldReturnType:
UseFieldReturnType<string, 'input', 'uncontrolled'> becomes UseFieldReturnType<string, 'input'>.
Removed @mantine/form types
Replace imports of ClearFieldDirty, SetFieldTouched, SetFieldDirty and
SetCalculatedFieldDirty with indexed form types, for example
UseFormReturnType<Values>['setTouched'].