Components

When you wrap your app with MD3Provider, every MUI component is automatically restyled to match the Material Design 3 specification. No extra imports or configuration needed.

What gets styled

• Button — pill-shaped (20 px radius), no uppercase, proper state layers
• IconButton — onSurfaceVariant colour with hover state
• FAB — rounded square, MD3 shadow, primaryContainer colour
• Card — elevated / filled / outlined variants with MD3 colours
• Paper — 12 px radius, no background-image tint
• AppBar — surface colour, zero elevation
• Drawer — surfaceContainerLow background
• TextField — outlined & filled with MD3 indicator colours
• Chip — 8 px radius, outline & filled styles
• Switch — wide-track MD3 toggle
• Dialog — 28 px border radius, surfaceContainerHigh background
• Tabs — primary indicator, secondary text
• BottomNavigation — surfaceContainer with active indicator pill
• Tooltip — inverseSurface background
• Snackbar — inverseSurface background
• Alert — MD3 container colours per severity
• Badge — error colour
• LinearProgress / CircularProgress — primary track & indicator
• Accordion — surface colour, outlineVariant divider
• Slider — primary track, secondaryContainer inactive

MD3 button variants

In addition to MUI's built-in contained, outlined, and text variants, md3-next adds two MD3-specific variants: tonal and elevated. These are type-safe via MUI module augmentation — no casting required.

import Button from "@mui/material/Button";

// Standard MUI variants — restyled to MD3
<Button variant="contained">Filled</Button>
<Button variant="outlined">Outlined</Button>
<Button variant="text">Text</Button>

// MD3-specific variants
<Button variant="tonal">Filled Tonal</Button>
<Button variant="elevated">Elevated</Button>

Module augmentation

md3-next augments MUI's ButtonPropsVariantOverrides interface so that variant="tonal" and variant="elevated" are recognised by TypeScript. This happens automatically when you import from "md3-next".

// This is handled internally — you don't need to add it yourself.
declare module "@mui/material/Button" {
  interface ButtonPropsVariantOverrides {
    tonal: true;
    elevated: true;
  }
}

Extending component styles

Since the theme is a standard MUI theme, you can layer additional overrides using createTheme or the sx prop as usual. The MD3 styles serve as the base.

import { useMD3 } from "md3-next";
import Button from "@mui/material/Button";

function CustomButton() {
  const { tokens } = useMD3();

  return (
    <Button
      variant="contained"
      sx={{
        bgcolor: tokens.tertiary,
        color: tokens.onTertiary,
        "&:hover": { bgcolor: tokens.tertiary },
      }}
    >
      Custom Tertiary
    </Button>
  );
}

MD3-Specific Components

In addition to restyling every MUI component, md3-next exports purpose-built MD3 components that have no MUI equivalent.

NavigationRail

A compact vertical navigation bar for tablet and desktop layouts. Features an active indicator pill, optional FAB slot, and configurable alignment.

import { NavigationRail } from "md3-next";
import HomeIcon from "@mui/icons-material/Home";
import SearchIcon from "@mui/icons-material/Search";
import SettingsIcon from "@mui/icons-material/Settings";

<NavigationRail
  items={[
    { key: "home", icon: <HomeIcon />, label: "Home" },
    { key: "search", icon: <SearchIcon />, label: "Search" },
    { key: "settings", icon: <SettingsIcon />, label: "Settings" },
  ]}
  value={selected}
  onChange={setSelected}
/>

SegmentedButton

A horizontal set of mutually exclusive options, following the MD3 spec for segmented buttons. Includes a check icon on the selected segment and supports full-width and small size variants.

import { SegmentedButton } from "md3-next";

<SegmentedButton
  items={[
    { value: "day", label: "Day" },
    { value: "week", label: "Week" },
    { value: "month", label: "Month" },
  ]}
  value={period}
  onChange={setPeriod}
/>

SearchBar

A rounded search input with leading and trailing icon slots, following the MD3 search bar specification. Supports full-width mode and an onSubmit callback for Enter key handling.

import { SearchBar } from "md3-next";
import SearchIcon from "@mui/icons-material/Search";
import MicIcon from "@mui/icons-material/Mic";

<SearchBar
  value={query}
  onChange={setQuery}
  placeholder="Search products..."
  leadingIcon={<SearchIcon />}
  trailingIcon={<MicIcon />}
/>

See all components in action on the Showcase page.