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:

Configuration

Inside app/layout.tsx, import the AppRouterCacheProvider and wrap all elements under the <body> with it:

app/layout.tsx

+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.

src/theme.ts

'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:

app/layout.tsx

 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:

src/theme.ts

 '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.

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:

Configuration

Inside the pages/_document.tsx file:

Import documentGetInitialProps and use it as the Document's getInitialProps.
Import DocumentHeadTags and render it inside the <Head>.

pages/_document.tsx

+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:

pages/_app.tsx

+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:

pages/_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:

pages/_document.tsx

+import { createEmotionCache } from '@mui/material-nextjs/v15-pagesRouter';
 ...

 MyDocument.getInitialProps = async (ctx) => {
   const finalProps = await documentGetInitialProps(ctx, {
+    emotionCache: createEmotionCache({ enableCssLayer: true }),
   });
   return finalProps;
 };

pages/_app.tsx

+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 the App component 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.

pages/_app.tsx

 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:

src/theme.ts

 'use client';
 const theme = createTheme({
+  cssVariables: true,
 });

Learn more about the advantages of CSS theme variables and how to prevent SSR flickering.