API Reference
Complete reference for every export from md3-next.
createMD3Theme(options)
Generates a complete MD3-themed configuration from a single seed colour. Returns an MD3Theme object you pass to MD3Provider.
import { createMD3Theme } from "md3-next";
const theme = createMD3Theme({
seed: "#6750A4",
mode: "system",
});Options — MD3ThemeOptions
| Prop / Field | Type | Default | Description |
|---|---|---|---|
seed | string | — | Hex colour (e.g. "#6750A4"). Required. |
mode | "light" | "dark" | "system" | "system" | Initial colour scheme preference. |
Returns — MD3Theme
| Prop / Field | Type | Default | Description |
|---|---|---|---|
light | Theme | — | MUI theme configured for light mode. |
dark | Theme | — | MUI theme configured for dark mode. |
mode | MD3Mode | — | The requested mode preference. |
seed | string | — | The original seed colour. |
tokens | { light: MD3ColorTokens; dark: MD3ColorTokens } | — | Raw MD3 colour tokens for both schemes. |
<MD3Provider>
Wraps your app with the correct MUI ThemeProvider and CssBaseline. Handles system preference detection and mode switching.
import { MD3Provider } from "md3-next";
<MD3Provider theme={theme}>
{children}
</MD3Provider>Props — MD3ProviderProps
| Prop / Field | Type | Default | Description |
|---|---|---|---|
theme | MD3Theme | — | The theme object from createMD3Theme. |
children | ReactNode | — | Your application tree. |
useMD3()
React hook to access the current MD3 context. Must be called inside an MD3Provider.
import { useMD3 } from "md3-next";
const { mode, preference, setMode, toggleMode, tokens, seed } = useMD3();Returns — MD3ContextValue
| Prop / Field | Type | Default | Description |
|---|---|---|---|
mode | "light" | "dark" | — | The currently resolved mode. |
preference | MD3Mode | — | The user's preference (may be "system"). |
setMode | (mode: MD3Mode) => void | — | Set the mode preference explicitly. |
toggleMode | () => void | — | Toggle between light and dark. |
tokens | MD3ColorTokens | — | Active colour tokens for the current mode. |
seed | string | — | The seed colour used to derive the palette. |
Low-level colour utilities
If you need tokens without building a full MUI theme, use these exports directly.
import { generateColorTokens, generateAllTokens } from "md3-next";
// Single scheme
const lightTokens = generateColorTokens("#6750A4", "light");
// Both schemes at once
const { light, dark } = generateAllTokens("#6750A4");generateColorTokens(seed, mode)
| Prop / Field | Type | Default | Description |
|---|---|---|---|
seed | string | — | Hex colour string. |
mode | "light" | "dark" | — | Which scheme to generate. |
Returns MD3ColorTokens — a flat object of hex strings.
generateAllTokens(seed)
| Prop / Field | Type | Default | Description |
|---|---|---|---|
seed | string | — | Hex colour string. |
Returns { light: MD3ColorTokens; dark: MD3ColorTokens }.
md3Typography
The MD3 type scale as a MUI ThemeOptions["typography"] object. Already applied by createMD3Theme, but exported if you need to reference or extend it.
import { md3Typography } from "md3-next";Exported types
import type {
MD3Theme,
MD3ThemeOptions,
MD3Mode,
MD3ProviderProps,
MD3ContextValue,
MD3ColorTokens,
} from "md3-next";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