Getting Started with md3-next

Getting Started

Get Material Design 3 running in your Next.js app in under five minutes.

Prerequisites

React 18+
Next.js 13+ (App Router recommended)
MUI v6+

Installation

npm

npm install md3-next @mui/material @emotion/react @emotion/styled

yarn

yarn add md3-next @mui/material @emotion/react @emotion/styled

pnpm

pnpm add md3-next @mui/material @emotion/react @emotion/styled

bun

bun add md3-next @mui/material @emotion/react @emotion/styled

Step 1 — Create a theme

Pick any hex colour as your seed. createMD3Theme generates the full MD3 token set for both light and dark schemes.

// app/theme.ts
import { createMD3Theme } from "md3-next";

const theme = createMD3Theme({
  seed: "#6750A4",   // your brand colour
  mode: "system",    // "light" | "dark" | "system"
});

export default theme;

Step 2 — Add the provider

Wrap your app with MD3Provider. It injects the MUI theme, CssBaseline, and a context for runtime mode switching.

// app/providers.tsx
"use client";

import { MD3Provider } from "md3-next";
import theme from "./theme";

export function Providers({ children }: { children: React.ReactNode }) {
  return <MD3Provider theme={theme}>{children}</MD3Provider>;
}

Step 3 — Wire up the root layout

// app/layout.tsx
import { Providers } from "./providers";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

Step 4 — Use tokens and controls

Access the current colour tokens and mode controls from any client component via the useMD3 hook.

"use client";

import { useMD3 } from "md3-next";

export function MyComponent() {
  const { mode, toggleMode, tokens } = useMD3();

  return (
    <div style={{ backgroundColor: tokens.surfaceContainer }}>
      <p style={{ color: tokens.onSurface }}>Current mode: {mode}</p>
      <button onClick={toggleMode}>Toggle theme</button>
    </div>
  );
}

Next.js Configuration

If you are using md3-next from a monorepo (workspace dependency), add it to transpilePackages so Next.js compiles it:

// next.config.ts
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  transpilePackages: ["md3-next"],
};

export default nextConfig;

That's it — every MUI component in your app is now styled to the Material Design 3 spec. Head to the Theming guide to learn about the full token set, or check the Components page to see what gets styled.

Want this pre-built?

Our templates come pre-configured with MD3Provider, theming, and fully styled layouts. Save hours of setup time.

View 6 Templates — from $29