Tailwind CSS v4 integration

Learn how to use Material UI with Tailwind CSS v4.

Frameworks

There are 2 steps to integrate Tailwind CSS v4 with Material UI:

Configure the styles to generate with @layer directive.
Set up layer order to have mui comes before utilities layer so that Tailwind CSS classes can override Material UI styles.

If you are using a framework, you can follow the instructions below to set up the integration.

Next.js App Router

Follow the App Router guide and do the following steps:

pass { enableCssLayer: true } to the options prop of AppRouterCacheProvider component.

src/app/layout.tsx

import { AppRouterCacheProvider } from '@mui/material-nextjs/v15-appRouter';
import GlobalStyles from '@mui/material/GlobalStyles';

export default function RootLayout() {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <AppRouterCacheProvider options={{ enableCssLayer: true }}>
          {/* Your app */}
        </AppRouterCacheProvider>
      </body>
    </html>
  );
}

configure layer order in the Tailwind CSS file.

src/app/globals.css

@layer theme, base, mui, components, utilities;
@import 'tailwindcss';

Next.js Pages Router

Follow the Pages Router guide and do the following steps:

pass a custom cache with { enableCssLayer: true } to documentGetInitialProps function.

pages/_document.tsx

import {
  createCache,
  documentGetInitialProps,
} from '@mui/material-nextjs/v15-pagesRouter';

// ...

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

configure the layer order with GlobalStyles component.

pages/_app.tsx

import { AppCacheProvider } from '@mui/material-nextjs/v15-pagesRouter';
import GlobalStyles from '@mui/material/GlobalStyles';

export default function MyApp(props: AppProps) {
  const { Component, pageProps } = props;
  return (
    <AppCacheProvider {...props}>
      <GlobalStyles styles="@layer theme, base, mui, components, utilities;" />
      {/* Your app */}
    </AppCacheProvider>
  );
}

Vite.js or any other SPA

Open src/main.tsx and do the following steps:

set enableCssLayer prop to StyledEngineProvider component.
configure the layer order with GlobalStyles component.

main.tsx

import { StyledEngineProvider } from '@mui/material/styles';
import GlobalStyles from '@mui/material/GlobalStyles';

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <StyledEngineProvider enableCssLayer>
      <GlobalStyles styles="@layer theme, base, mui, components, utilities;" />
      {/* Your app */}
    </StyledEngineProvider>
  </React.StrictMode>,
);

Tailwind IntelliSense for VS Code

Follow the installation and add the following configuration to your settings.json file.

{
  // ...config
  "tailwindCSS.experimental.classRegex": [["className\\s*:\\s*['\"]([^'\"]*)['\"]"]]
}

This will enable Tailwind CSS IntelliSense for any value that has key className.

Usage

Use className prop to apply Tailwind CSS classes to the root element of the component.
Use slotProps.{slotName}.className to apply Tailwind CSS classes to the interior slot of the component.

Troubleshooting

If the Tailwind CSS classes are not overriding Material UI components, make sure that:

You are using at least Tailwind CSS v4.
You have configured the layer order correctly by checking the DevTools styles tab. The mui layer should come before the utilities layer.