7.x → 8.x migration guide
Global styles imports
If you used separate styles imports from @mantine/core/styles/global.css
, you need to update imports to use new files.
Note that if you previously imported @mantine/core/styles.css
, no changes are required – all new files are already included in styles.css
.
7.x version import:
8.x version import:
If you used @mantine/core/styles.css
, no changes are required,
the import works the same in 7.x and 8.x versions:
Portal reuseTargetNode
reuseTargetNode
prop of Portal component is now enabled by default.
This option improves performance by reusing the target node between portal renders, but
in some edge cases, it might cause issues with z-index
stacking context.
If you experience issues with z-index
, change reuseTargetNode
prop to false
in theme:
Switch withThumbIndicator
Switch component default styles were updated, it now
includes checked state indicator inside the thumb. If you want to use
old styles without indicator, set withThumbIndicator
prop to false
in theme:
Date string values
@mantine/dates
components now use date string values in onChange
and other callbacks.
If you want to continue using @mantine/dates
components the same way as in 7.x, you need
to convert callback values to Date
objects:
DatesProvider timezone
DatesProvider
component no longer supports timezone
option:
If you need to handle timezones in your application, you can use a dedicated dates library (dayjs, luxon, date-fns) to update timezone values. Example of using Mantine components with dayjs:
DateTimePicker timeInputProps
DateTimePicker component no longer accepts timeInputProps
prop,
as the underlying TimeInput component was replaced with TimePicker.
To pass props down to TimePicker component, use timePickerProps
prop instead.
7.x version:
8.x version:
CodeHighlight usage
@mantine/code-highlight package no longer depends on highlight.js. You can follow the updated documentation to set up syntax highlighting with shiki.
If you want to continue using highlight.js, in your application,
install highlight.js
package:
Then wrap your app with CodeHighlightAdapterProvider
and provide createHighlightJsAdapter
as adapter
prop:
Then you need to add styles of one of the highlight.js themes to your application.
You can do that by importing css file from highlight.js
package or adding it via
CDN link to the head of your application:
After that, you can use CodeHighlight
component in your application the same way you did in 7.x version.
Menu data-hovered attribute
Menu.Item no longer uses data-hovered
attribute to indicate hovered state.
If you used data-hovered
in your styles, you need to change it :hover
and :focus
selectors
instead:
Popover hideDetached
Popover now supports hideDetached
prop to automatically close popover when target element is removed from the DOM:
By default, hideDetached
is enabled – the behavior has changed from 7.x version.
If you prefer to keep the old behavior, you can disable hideDetached
for all components:
Carousel changes
Starting from 8.x version, @mantine/carousel package requires
embla-carousel
and embla-carousel-react
packages with version 8.x.
You need to update embla dependencies:
Update embla props that were previously passed to Carousel
component
to emblaOptions
. Full list of props:
loop
align
slidesToScroll
dragFree
inViewThreshold
skipSnaps
containScroll
speed
anddraggable
props were removed – they are no longer supported by embla
useAnimationOffsetEffect
hook was removed, it is no longer required, you need to
remove it from your code:
Embla
type is no longer exported from @mantine/carousel
package,
you need to change this import to reference embla-carousel
package instead: