8.x → 9.x migration guide

Migrate with LLM agents

You can use LLM agents to assist with the migration from 8.x to 9.x. The LLM documentation includes all breaking changes and migration steps in a format optimized for AI coding tools. Copy the link to the md documentation file and ask your AI agent to perform the migration for you.

Migrate with LLM

Prerequisites

Mantine 9.x requires React 19.2 or later. Update React before migrating. If you cannot update React yet, continue using Mantine 8.x.

Update dependencies

Update all @mantine/* packages to version 9.7.3
If you use @mantine/tiptap package, update all @tiptap/* packages to the latest 3.x version
If you use @mantine/charts package, update recharts to the latest 3.x version

use-form TransformValues type

The second generic type of the useForm hook is now the type of transformed values instead of the transform function type. New usage example:

import { useForm } from '@mantine/form';

interface FormValues {
  name: string;
  locationId: string;
}

interface TransformedValues {
  name: string;
  locationId: number;
}

function Demo() {
  const form = useForm<FormValues, TransformedValues>({
    mode: 'uncontrolled',
    initialValues: {
      name: '',
      locationId: '2',
    },

    transformValues: (values) => ({
      ...values,
      locationId: Number(values.locationId),
    }),
  });
}

Text color prop

The color prop of the Text and Anchor components was removed. Use the c style prop instead:

import { Text } from '@mantine/core';

// ❌ No longer works
function Demo() {
  return <Text color="red">Text</Text>;
}

// ✅ Use the c style prop
function Demo() {
  return <Text c="red">Text</Text>;
}

Light variant color changes

In Mantine 9, the light variant CSS variables were changed to use solid color values instead of transparency. If you need to keep 8.x behavior during migration, use v8CssVariablesResolver:

import {
  Button,
  MantineProvider,
  v8CssVariablesResolver,
} from '@mantine/core';

function Demo() {
  return (
    <MantineProvider cssVariablesResolver={v8CssVariablesResolver}>
      <Button variant="light" color="blue.6">
        Uses 8.x light variant colors
      </Button>
    </MantineProvider>
  );
}

Form resolvers

In 9.x, @mantine/form has built-in support for Standard Schema. If your schema library supports Standard Schema (Zod v4, Valibot, ArkType), use the built-in schemaResolver instead of a dedicated resolver package:

Example with 8.x:

import { z } from 'zod';
// ❌ No longer works; zodResolver is not exported from @mantine/form
import { useForm, zodResolver } from '@mantine/form';

const schema = z.object({
  email: z.string().email({ message: 'Invalid email' }),
});

const form = useForm({
  initialValues: { email: '' },
  validate: zodResolver(schema),
});

Example with 9.x using Standard Schema (recommended):

import { z } from 'zod/v4';
import { useForm, schemaResolver } from '@mantine/form';

const schema = z.object({
  email: z.email({ error: 'Invalid email' }),
});

const form = useForm({
  initialValues: { email: '' },
  validate: schemaResolver(schema, { sync: true }),
});

TypographyStylesProvider

The TypographyStylesProvider component was renamed to Typography:

// ❌ No longer works
import { TypographyStylesProvider } from '@mantine/core';

// ✅ Use the Typography component
import { Typography } from '@mantine/core';

Popover and Tooltip positionDependencies prop

The Popover and Tooltip components no longer accept the positionDependencies prop. Remove it, the position is now recalculated automatically.

import { Popover } from '@mantine/core';

// ❌ positionDependencies is no longer needed
function Demo(props) {
  return (
    <Popover position="top" positionDependencies={[props.a, props.b]}>
      {/* ... */}
    </Popover>
  );
}

// ✅ The position is recalculated automatically
function Demo(props) {
  return (
    <Popover position="top">
      {/* ... */}
    </Popover>
  );
}

use-fullscreen hook changes

The use-fullscreen hook was split into two hooks: useFullscreenElement and useFullscreenDocument.

New usage with the document element:

import { useFullscreenDocument } from '@mantine/hooks';
import { Button } from '@mantine/core';

function Demo() {
  const { toggle, fullscreen } = useFullscreenDocument();

  return (
    <Button onClick={toggle} color={fullscreen ? 'red' : 'blue'}>
      {fullscreen ? 'Exit Fullscreen' : 'Enter Fullscreen'}
    </Button>
  );
}

New usage with a custom target element:

import { useFullscreenElement } from '@mantine/hooks';
import { Button, Stack } from '@mantine/core';

function RefDemo() {
  const { ref, toggle, fullscreen } = useFullscreenElement();

  return (
    <Stack align="center">
      <img
        ref={ref}
        src="https://raw.githubusercontent.com/mantinedev/mantine/master/.demo/images/bg-4.png"
        alt="For demo"
        width={200}
      />
      <Button onClick={toggle} color={fullscreen ? 'red' : 'blue'}>
        {fullscreen ? 'Exit Fullscreen' : 'View Image Fullscreen'}
      </Button>
    </Stack>
  );
}

use-mouse hook changes

The use-mouse hook was split into two hooks: useMouse and useMousePosition. useMouse now tracks the position over the element that ref is assigned to, use useMousePosition to track the position over the document.

Previous usage with the document element:

import { Text, Code } from '@mantine/core';
import { useMouse } from '@mantine/hooks';

function Demo() {
  const { x, y } = useMouse();

  return (
    <Text ta="center">
      Mouse coordinates <Code>{`{ x: ${x}, y: ${y} }`}</Code>
    </Text>
  );
}

New usage with document:

Mouse coordinates { x: 0, y: 0 }

import { Text, Code } from '@mantine/core';
import { useMousePosition } from '@mantine/hooks';

function Demo() {
  const { x, y } = useMousePosition();

  return (
    <Text ta="center">
      Mouse coordinates <Code>{`{ x: ${x}, y: ${y} }`}</Code>
    </Text>
  );
}

use-mutation-observer hook changes

The use-mutation-observer hook now uses the new callback ref approach. To observe an external element, use useMutationObserverTarget instead.

Previous usage (8.x):

import { useMutationObserver } from '@mantine/hooks';

useMutationObserver(
  (mutations) => console.log(mutations),
  { childList: true },
  // ❌ The third argument is no longer supported; use `useMutationObserverTarget` instead
  document.getElementById('external-element')
);

New usage (9.x):

import { useMutationObserverTarget } from '@mantine/hooks';

// ✅ Rename the hook to `useMutationObserverTarget`
useMutationObserverTarget(
  (mutations) => console.log(mutations),
  { childList: true },
  // ✅ Pass the target element as the third argument
  document.getElementById('external-element')
);

Rename hooks types

@mantine/hooks types were renamed for consistency; rename them in your codebase:

UseScrollSpyReturnType → UseScrollSpyReturnValue
StateHistory → UseStateHistoryValue
OS → UseOSReturnValue

Collapse in -> expanded

The Collapse component now uses the expanded prop instead of in:

import { Collapse } from '@mantine/core';

// ❌ No longer works
function Demo() {
  return (
    <Collapse in={false}>
      {/* ... */}
    </Collapse>
  );
}

// ✅ Use the expanded prop
function Demo() {
  return (
    <Collapse expanded={false}>
      {/* ... */}
    </Collapse>
  );
}

Spoiler initialState -> defaultExpanded

The Spoiler component's initialState prop was renamed to defaultExpanded for consistency with other Mantine components:

import { Spoiler } from '@mantine/core';

// ❌ No longer works
function Demo() {
  return (
    <Spoiler initialState={false} showLabel="Show" hideLabel="Hide">
      {/* ... */}
    </Spoiler>
  );
}

// ✅ Use the defaultExpanded prop
function Demo() {
  return (
    <Spoiler defaultExpanded={false} showLabel="Show" hideLabel="Hide">
      {/* ... */}
    </Spoiler>
  );
}

Grid gutter -> gap

The Grid component gutter prop was renamed to gap for consistency with other layout components (like Flex and SimpleGrid). Additionally, new rowGap and columnGap props were added to allow separate control of vertical and horizontal spacing:

import { Grid } from '@mantine/core';

// ❌ No longer works
function Demo() {
  return (
    <Grid gutter="xl">
      <Grid.Col span={6}>1</Grid.Col>
      <Grid.Col span={6}>2</Grid.Col>
    </Grid>
  );
}

// ✅ Use the gap prop
function Demo() {
  return (
    <Grid gap="xl">
      <Grid.Col span={6}>1</Grid.Col>
      <Grid.Col span={6}>2</Grid.Col>
    </Grid>
  );
}

// ✅ New: Separate row and column gaps
function Demo() {
  return (
    <Grid rowGap="xl" columnGap="sm">
      <Grid.Col span={6}>1</Grid.Col>
      <Grid.Col span={6}>2</Grid.Col>
    </Grid>
  );
}

Grid overflow="hidden" no longer required

The Grid component now uses native CSS gap property instead of negative margins. Remove overflow="hidden" from your Grid components, it is no longer needed to prevent content overflow:

import { Grid } from '@mantine/core';

// ❌ overflow="hidden" is no longer needed
function Demo() {
  return (
    <Grid overflow="hidden">
      <Grid.Col span={6}>1</Grid.Col>
      <Grid.Col span={6}>2</Grid.Col>
    </Grid>
  );
}

// ✅ Remove overflow="hidden"
function Demo() {
  return (
    <Grid>
      <Grid.Col span={6}>1</Grid.Col>
      <Grid.Col span={6}>2</Grid.Col>
    </Grid>
  );
}

useLocalStorage and useSessionStorage return type

The useLocalStorage and useSessionStorage hooks now include undefined in the return type when no defaultValue is provided. Update your code to handle undefined or provide defaultValue:

import { useLocalStorage } from '@mantine/hooks';

// ❌ In 8.x, `value` was typed as `string` (incorrect)
const [value, setValue] = useLocalStorage({ key: 'my-key' });

// ✅ In 9.x, `value` is typed as `string | undefined`
const [value, setValue] = useLocalStorage({ key: 'my-key' });

// ✅ Provide defaultValue to keep the previous non-undefined type
const [value, setValue] = useLocalStorage({
  key: 'my-key',
  defaultValue: '',
});

The same change applies to readLocalStorageValue and readSessionStorageValue.

useHeadroom returns object instead of boolean

The useHeadroom hook now returns an object with pinned and scrollProgress properties instead of a boolean:

import { useHeadroom } from '@mantine/hooks';

// ❌ In 8.x, the return type is plain boolean
const pinned = useHeadroom({ fixedAt: 120 });

// ✅ In 9.x, the return type is an object containing `pinned` property
const { pinned } = useHeadroom({ fixedAt: 120 });

Default border-radius change

In 8.x, the default border-radius (theme.defaultRadius) was sm (4px). In 9.x, the default border-radius was changed to md (8px). To keep the previous behavior, set defaultRadius to sm in the theme:

import { createTheme, MantineProvider } from '@mantine/core';

const theme = createTheme({
  defaultRadius: 'sm',
});

function Demo() {
  return <MantineProvider theme={theme}>{/* Your app */}</MantineProvider>;
}

Notifications pauseResetOnHover default change

In 8.x, hovering over a notification paused the auto close timer only for that notification. In 9.x, hovering over any notification pauses the auto close timer of all visible notifications. To keep the previous behavior, set pauseResetOnHover="notification":

import { Notifications } from '@mantine/notifications';

function Demo() {
  return <Notifications pauseResetOnHover="notification" />;
}

7.x to 8.x migration

Migration guide Tiptap 2 → Tiptap 3