Next.js integration
Learn how to use Material UI with Next.js.
App Router
This section walks through the Material UI integration with the Next.js App Router, an evolution of the Pages Router, and, currently, the recommended way of building new Next.js applications starting from version 13.
Installing the dependencies
Start by ensuring that you already have
@mui/material and
next installed. Then, run one of
the following commands to install the
dependencies:
npm install @mui/material-nextjs @emotion/cache
Configuration
Inside app/layout.tsx, import the
AppRouterCacheProvider and wrap all
elements under the
<body> with it:
+import { AppRouterCacheProvider } from '@mui/material-nextjs/v15-appRouter';
// or `v1X-appRouter` if you are using Next.js v1X
export default function RootLayout(props) {
return (
<html lang="en">
<body>
+ <AppRouterCacheProvider>
{props.children}
+ </AppRouterCacheProvider>
</body>
</html>
);
}
Custom cache (optional)
Use the options prop to override
the default
cache options—for example, the code snippet below shows how
to change the CSS key to css (the
default is mui):
<AppRouterCacheProvider
+ options={{ key: 'css' }}
>
{children}
</AppRouterCacheProvider>
Font optimization
To integrate
Next.js font optimization
with Material UI, create a new file with the
'use client'; directive.
Then create a theme using
var(--font-roboto) as a value for
the typography.fontFamily field.
'use client';
import { createTheme } from '@mui/material/styles';
const theme = createTheme({
typography: {
fontFamily: 'var(--font-roboto)',
},
});
export default theme;
Finally, in src/app/layout.tsx,
pass the theme to the
ThemeProvider:
import { AppRouterCacheProvider } from '@mui/material-nextjs/v15-appRouter';
+import { Roboto } from 'next/font/google';
+import { ThemeProvider } from '@mui/material/styles';
+import theme from '../theme';
+const roboto = Roboto({
+ weight: ['300', '400', '500', '700'],
+ subsets: ['latin'],
+ display: 'swap',
+ variable: '--font-roboto',
+});
export default function RootLayout(props) {
const { children } = props;
return (
+ <html lang="en" className={roboto.variable}>
<body>
<AppRouterCacheProvider>
+ <ThemeProvider theme={theme}>
{children}
+ </ThemeProvider>
</AppRouterCacheProvider>
</body>
</html>
);
}
To learn more about theming, check out the theming guide page.
CSS theme variables
To use
CSS theme variables, enable the cssVariables flag:
'use client';
const theme = createTheme({
+ cssVariables: true,
});
Learn more about the advantages of CSS theme variables and how to prevent SSR flickering.
Using other styling solutions
If you are using a styling solution other than
Emotion to customize Material UI components, set
enableCssLayer: true in the
options prop:
<AppRouterCacheProvider options={{ enableCssLayer: true }}>
This option ensures that the styles generated by
Material UI will be wrapped in a CSS
@layer mui rule, which is
overridden by anonymous layer styles when using
Material UI with CSS Modules, Tailwind CSS, or
even plain CSS without using
@layer.
To learn more about it, see the MDN CSS layer documentation.
Next.js v16 Client Component restriction
If you encounter
Functions cannot be passed directly to
Client Components
error from passing Next.js Link to Material UI
component prop, you need to create
a wrapper component with
use client directive like the
following:
'use client';
import Link, { LinkProps } from 'next/link';
export default Link;
Then, replace the Next.js Link with the wrapper component:
- import Link from 'next/link';
+ import Link from '../components/Link';
...
<Button component={Link} href="/about" variant="contained">
Go to About Page
</Button>
URL-driven UI and the Suspense boundary
When client components use Next.js App Router
hooks that read the URL—for example
useSearchParams() from
next/navigation for filters, tabs,
or pagination—Next.js expects a
<Suspense> boundary around
that part of the React tree. Without it, you may
see build failures or runtime messages about a
missing Suspense boundary (behavior depends on
your Next.js version and static vs dynamic
rendering).
This pattern is common with Material UI:
Table, Tabs,
TextField, and other controls are
often implemented as client components that sync
to the query string.
Recommended structure: keep
page.tsx as a server component when
possible, and wrap only the client subtree that
calls useSearchParams in
<Suspense>.
Avoid fallback={null} (or an empty
fallback) for UI that reserves space in the
layout (toolbars, filters, tab bars, and
similar). The server and the initial streamed
HTML then omit that subtree, and the real
content appears only after the client hydrates,
which often causes layout shift and hurts CLS.
Prefer a fallback whose size and structure
approximate the final UI, for example
Material UI Skeleton inside
Stack or Box with the
same minHeight, flex direction, and
breakpoints as the loaded component.
import { Suspense } from 'react';
import Box from '@mui/material/Box';
import Skeleton from '@mui/material/Skeleton';
import Stack from '@mui/material/Stack';
import OrdersToolbar from './OrdersToolbar';
function OrdersToolbarFallback() {
return (
<Stack
direction="row"
spacing={2}
useFlexGap
sx={{ flexWrap: 'wrap', alignItems: 'center', minHeight: 56 }}
>
<Skeleton
variant="rounded"
height={40}
sx={{ minWidth: 200, flexGrow: { xs: 1, sm: 0 } }}
/>
<Skeleton variant="rounded" width={120} height={40} />
<Box sx={{ flexGrow: 1 }} />
<Skeleton variant="rounded" width={100} height={40} />
</Stack>
);
}
export default function Page() {
return (
<Suspense fallback={<OrdersToolbarFallback />}>
<OrdersToolbar />
</Suspense>
);
}
OrdersToolbar would be a file
marked with
'use client' that calls
useSearchParams() and renders
Material UI components. Adjust the
fallback's layout and Skeleton sizes so they
match your real toolbar (or filter row) as
closely as possible.
For details and version-specific notes, see the
Next.js documentation for
useSearchParams.
Pages Router
This section walks through the Material UI integration with the Next.js Pages Router, for both Server-side Rendering (SSR) and Static Site Generation (SSG).
Installing the dependencies
Start by ensuring that you already have
@mui/material and
next installed. Then, run one of
the following commands to install the
dependencies:
npm install @mui/material-nextjs @emotion/cache @emotion/server
Configuration
Inside the
pages/_document.tsx file:
-
Import
documentGetInitialPropsand use it as the Document'sgetInitialProps. -
Import
DocumentHeadTagsand render it inside the<Head>.
+import {
+ DocumentHeadTags,
+ documentGetInitialProps,
+} from '@mui/material-nextjs/v15-pagesRouter';
// or `v1X-pagesRouter` if you are using Next.js v1X
export default function MyDocument(props) {
return (
<Html lang="en">
<Head>
+ <DocumentHeadTags {...props} />
...
</Head>
<body>
<Main />
<NextScript />
</body>
</Html>
);
}
+MyDocument.getInitialProps = async (ctx) => {
+ const finalProps = await documentGetInitialProps(ctx);
+ return finalProps;
+};
Then, inside pages/_app.tsx, import
the AppCacheProvider component and
render it as the root element:
+import { AppCacheProvider } from '@mui/material-nextjs/v15-pagesRouter';
// Or `v1X-pages` if you are using Next.js v1X
export default function MyApp(props) {
return (
+ <AppCacheProvider {...props}>
<Head>
...
</Head>
...
+ </AppCacheProvider>
);
}
Custom cache (optional)
To use a custom
Emotion cache, pass it to the
emotionCache property in
_document.tsx:
...
MyDocument.getInitialProps = async (ctx) => {
const finalProps = await documentGetInitialProps(ctx, {
+ emotionCache: createCustomCache(),
});
return finalProps;
};
Cascade layers (optional)
To enable
cascade layers
(@layer), create a new cache with
enableCssLayer: true and pass it to
the emotionCache property in both
_document.tsx and
_app.tsx:
+import { createEmotionCache } from '@mui/material-nextjs/v15-pagesRouter';
...
MyDocument.getInitialProps = async (ctx) => {
const finalProps = await documentGetInitialProps(ctx, {
+ emotionCache: createEmotionCache({ enableCssLayer: true }),
});
return finalProps;
};
+import { createEmotionCache } from '@mui/material-nextjs/v15-pagesRouter';
...
const clientCache = createEmotionCache({ enableCssLayer: true });
+ export default function MyApp({ emotionCache = clientCache }) {
return (
+ <AppCacheProvider emotionCache={emotionCache}>
<Head>
...
</Head>
...
</AppCacheProvider>
);
}
App enhancement (optional)
Pass an array to the
plugins property to enhance the app
with additional features, like
server-side-rendered styles if you're using
JSS and styled-components.
Each plugin must have the following properties:
-
enhanceApp: a higher-order component that receives theAppcomponent and returns a new app component. -
resolveProps: a function that receives the initial props and returns a new props object.
When run, enhanceApp from each
plugin is called first, from top to bottom, and
then the process is repeated for
resolveProps.
import { ServerStyleSheet } from 'styled-components';
MyDocument.getInitialProps = async (ctx) => {
const jssSheets = new JSSServerStyleSheets();
const styledComponentsSheet = new ServerStyleSheet();
try {
const finalProps = await documentGetInitialProps(ctx, {
emotionCache: createEmotionCache(),
plugins: [
{
// styled-components
enhanceApp: (App) => (props) =>
styledComponentsSheet.collectStyles(<App {...props} />),
resolveProps: async (initialProps) => ({
...initialProps,
styles: [
styledComponentsSheet.getStyleElement(),
...initialProps.styles,
],
}),
},
{
// JSS
enhanceApp: (App) => (props) => jssSheets.collect(<App {...props} />),
resolveProps: async (initialProps) => {
const css = jssSheets.toString();
return {
...initialProps,
styles: [
...initialProps.styles,
<style
id="jss-server-side"
key="jss-server-side"
// eslint-disable-next-line react/no-danger
dangerouslySetInnerHTML={{ __html: css }}
/>,
<style id="insertion-point-jss" key="insertion-point-jss" />,
],
};
},
},
],
});
return finalProps;
} finally {
styledComponentsSheet.seal();
}
};
TypeScript
If you are using TypeScript, add
DocumentHeadTagsProps to the
Document's props interface:
+import type { DocumentHeadTagsProps } from '@mui/material-nextjs/v15-pagesRouter';
// or `v1X-pagesRouter` if you are using Next.js v1X
+export default function MyDocument(props: DocumentProps & DocumentHeadTagsProps) {
...
}
Font optimization
To integrate
Next.js font optimization
with Material UI, open
pages/_app.tsx and create a theme
using var(--font-roboto) as a value
for the
typography.fontFamily field.
import * as React from 'react';
import Head from 'next/head';
import { AppProps } from 'next/app';
import { AppCacheProvider } from '@mui/material-nextjs/v15-pagesRouter';
+import { ThemeProvider, createTheme } from '@mui/material/styles';
+import { Roboto } from 'next/font/google';
+const roboto = Roboto({
+ weight: ['300', '400', '500', '700'],
+ subsets: ['latin'],
+ display: 'swap',
+ variable: '--font-roboto',
+});
+const theme = createTheme({
+ typography: {
+ fontFamily: 'var(--font-roboto)',
+ },
+});
export default function MyApp(props: AppProps) {
const { Component, pageProps } = props;
return (
<AppCacheProvider {...props}>
<Head>...</Head>
+ <ThemeProvider theme={theme}>
+ <main className={roboto.variable}>
<Component {...pageProps} />
+ </main>
+ </ThemeProvider>
</AppCacheProvider>
);
}
To learn more about theming, check out the Theming guide.
CSS theme variables
To use
CSS theme variables, enable the cssVariables flag:
'use client';
const theme = createTheme({
+ cssVariables: true,
});
Learn more about the advantages of CSS theme variables and how to prevent SSR flickering.