md3-next
v0.1.3
Published
Material Design 3 theme and components for Next.js with MUI
Readme
md3-next
Material Design 3 theme and components for Next.js — powered by MUI.
Generate a full MD3 colour scheme from a single seed colour, get automatic light/dark mode, and have every MUI component styled to match the Material Design 3 spec.
Documentation · Components · Theming · API Reference
Looking for a head start? Check out our premium templates — production-ready Next.js apps built with md3-next.
Installation
npm install md3-next @mui/material @emotion/react @emotion/styledQuick Start
// app/theme.ts
import { createMD3Theme } from "md3-next";
const theme = createMD3Theme({
seed: "#6750A4",
mode: "system",
});
export default theme;// 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>;
}// 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>
);
}What You Get
From a single seed colour, createMD3Theme generates the full MD3 token set:
| Token | Description |
| ----------------------------------------------- | ------------------------------------------ |
| primary / onPrimary | Primary brand colour and its contrast text |
| primaryContainer / onPrimaryContainer | Lighter primary for containers |
| secondary / onSecondary | Secondary colour pair |
| secondaryContainer / onSecondaryContainer | Secondary container pair |
| tertiary / onTertiary | Tertiary accent pair |
| surface / onSurface | Default surface and text |
| surfaceContainer / surfaceContainerHigh / … | MD3 surface hierarchy |
| outline / outlineVariant | Border and divider colours |
| error / onError / errorContainer | Error states |
| inverseSurface / inverseOnSurface | Snackbar / tooltip surfaces |
All tokens are available for both light and dark schemes.
Using Tokens
Access the current colour tokens and mode controls in any client component:
"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</button>
</div>
);
}MD3 Button Variants
The theme adds two MD3-specific button variants on top of MUI's defaults:
<Button variant="contained">Filled</Button>
<Button variant="tonal">Filled Tonal</Button>
<Button variant="elevated">Elevated</Button>
<Button variant="outlined">Outlined</Button>
<Button variant="text">Text</Button>Styled Components
Every MUI component is automatically themed to match the MD3 spec:
- Buttons — pill-shaped, no uppercase, proper state layers
- Cards — elevated / filled / outlined variants
- FAB — rounded square, MD3 shadow, primaryContainer colour
- Chips — 8 px radius, outline & filled styles
- Switch — wide-track MD3 toggle
- Text Fields — outlined and filled with MD3 indicator colours
- Dialogs — extra-large radius, surfaceContainerHigh background
- Navigation — bottom nav, tabs, drawer styled to spec
- App Bar — surface colour, no elevation
- Typography, badges, progress indicators, tooltips, snackbars, alerts…
API Reference
createMD3Theme(options)
| Option | Type | Default | Description |
| ------ | ------------------------------- | ---------- | ----------------------------- |
| seed | string | — | Hex colour (e.g. "#6750A4") |
| mode | "light" \| "dark" \| "system" | "system" | Colour scheme preference |
Returns an MD3Theme object containing .light and .dark MUI themes, the raw .tokens, and the .seed.
<MD3Provider theme={md3Theme}>
Wraps your app with the correct MUI ThemeProvider and CssBaseline. Handles system preference detection and mode switching.
useMD3()
Returns { mode, preference, setMode, toggleMode, tokens, seed }.
License
MIT