web-ui-mui

MUI (Material UI) Patterns

Quick Guide: MUI provides pre-styled React components implementing Material Design. Use createTheme + ThemeProvider for global theming, sx prop for one-off styles, styled() for reusable styled components, and slots/slotProps for deep component customization. Prefer path imports in development for faster builds. Current: v7.x (March 2025) -- CSS layers support, standardized slot pattern, Grid v2 promoted, React 19 compatible. MUI X v8 for DataGrid, DatePicker, Charts.

<critical_requirements>

CRITICAL: Before Using This Skill

All code must follow project conventions in CLAUDE.md (kebab-case, named exports, import ordering, import type, named constants)

(You MUST wrap the app in ThemeProvider with a createTheme() instance -- never use MUI components without a theme)

(You MUST use path imports (@mui/material/Button) in development for faster startup -- barrel imports (@mui/material) cause 6x slower dev builds)

(You MUST use slots/slotProps for component inner-element customization -- componentsProps is deprecated in v7)

(You MUST use theme.applyStyles('dark', {...}) for dark mode conditional styles -- never use theme.palette.mode === 'dark' which causes flickering)

</critical_requirements>

Auto-detection: MUI, Material UI, @mui/material, @mui/system, @mui/icons-material, @mui/x-data-grid, @mui/x-date-pickers, createTheme, ThemeProvider, sx prop, styled, CssBaseline, useTheme, useMediaQuery, DataGrid, DatePicker, AppBar, Drawer, Dialog, Snackbar, TextField, Autocomplete, slotProps

When to use:

• Building React applications with pre-styled Material Design components
• Creating themed UIs with consistent design tokens (palette, typography, spacing)
• Implementing complex data views with DataGrid, DatePicker, or Charts (MUI X)
• Building admin dashboards, forms, and CRUD interfaces rapidly

When NOT to use:

• Headless/unstyled components needed (use a headless component library instead)
• Minimal bundle size is critical (MUI adds significant weight)
• Non-Material Design aesthetic required without heavy theme customization
• Server Components needed as primary rendering strategy (MUI components are client-only)

Key patterns covered:

• Theme setup, color schemes, and dark mode
• sx prop styling (theme-aware, responsive, callbacks)
• styled() API for reusable components
• Slots/slotProps for component customization (v7)
• Layout components (Grid, Stack, Box, Container)
• TypeScript theme augmentation

Detailed Resources:

• [examples/core.md](examples/core.md) -- ThemeProvider, createTheme, CssBaseline, color schemes, dark mode toggle, TypeScript augmentation, Next.js integration, CSS layers
• [examples/form-inputs.md](examples/form-inputs.md) -- TextField, Select, Autocomplete, slots/slotProps customization
• [examples/layout.md](examples/layout.md) -- Grid, Stack, Box, Container, responsive card grid
• [examples/data-grid.md](examples/data-grid.md) -- @mui/x-data-grid columns, pagination, custom rendering
• [examples/feedback.md](examples/feedback.md) -- Dialog, Snackbar, Alert, Skeleton, CircularProgress
• [examples/navigation.md](examples/navigation.md) -- AppBar, Drawer, Tabs, responsive dashboard layout
• [examples/styling.md](examples/styling.md) -- styled() API, sx prop patterns, dark mode styling, custom props
• [reference.md](reference.md) -- Decision frameworks, anti-patterns, quick reference tables

<philosophy>

Philosophy

MUI implements Material Design as a comprehensive React component library. It provides:

• Design System: Complete palette, typography, spacing, shadows, and breakpoint tokens
• Pre-styled Components: 50+ components with consistent visual language
• Customization Layers: From simple sx overrides to deep theme-level component restyling
• Accessibility: Built-in ARIA attributes, keyboard navigation, and focus management

Core Principle: Theme drives everything. Define your design tokens in createTheme(), and all components inherit consistent styling. Override at the component level with sx, styled(), or slots/slotProps.

MUI v7 Key Changes (March 2025):

• CSS layers support via enableCssLayer (integrates with utility-first CSS frameworks)
• Standardized slots/slotProps across all components (replaces components/componentsProps)
• Grid v2 promoted to Grid (old Grid renamed to GridLegacy)
• Lab components graduated to @mui/material (Alert, Skeleton, Autocomplete, etc.)
• Package layout updated for ESM/CJS dual support (no deep imports beyond one level)
• React 19 full compatibility

Pigment CSS Status: MUI's zero-runtime CSS-in-JS engine is currently on hold / alpha. Production apps should continue using the default Emotion-based styling engine.

</philosophy>

<patterns>

Core Patterns

Pattern 1: Theme Setup and Configuration

Every MUI app starts with createTheme() and ThemeProvider. The theme defines all design tokens.

import { createTheme, ThemeProvider, CssBaseline } from "@mui/material";

const theme = createTheme({
  palette: {
    primary: { main: "#1976d2" },
    secondary: { main: "#9c27b0" },
  },
  typography: {
    fontFamily: '"Inter", "Roboto", "Helvetica", "Arial", sans-serif',
    button: { textTransform: "none" },
  },
  shape: { borderRadius: 8 },
  spacing: 8,
});

function App({ children }: { children: React.ReactNode }) {
  return (
    <ThemeProvider theme={theme}>
      <CssBaseline />
      {children}
    </ThemeProvider>
  );
}

export { App };

Why good: Centralized design tokens, CssBaseline normalizes cross-browser styles, all children inherit theme

For production-ready theme with color schemes, dark mode, component overrides, and TypeScript augmentation, see [examples/core.md](examples/core.md).

Pattern 2: CSS Variables and Dark Mode

MUI v7 supports CSS variables natively. Use colorSchemes for flicker-free light/dark mode.

const theme = createTheme({
  cssVariables: { colorSchemeSelector: "data" },
  colorSchemes: {
    light: { palette: { primary: { main: "#1976d2" } } },
    dark: { palette: { primary: { main: "#90caf9" } } },
  },
});

Toggle with the useColorScheme hook:

import { useColorScheme } from "@mui/material/styles";
const { mode, setMode } = useColorScheme();
setMode(mode === "light" ? "dark" : "light");

Why good: CSS variables prevent flash of wrong theme on SSR, persists preference to localStorage

// BAD: Causes SSR flicker
backgroundColor: theme.palette.mode === "dark" ? "#333" : "#fff";
// GOOD: Use applyStyles in styled()
...theme.applyStyles("dark", { backgroundColor: "#1a1a2e" });

For full dark mode toggle component, see [examples/core.md](examples/core.md).

Pattern 3: The sx Prop

The sx prop is MUI's primary styling escape hatch. It accesses theme values, supports responsive breakpoints, and handles pseudo-selectors.

<Box
  sx={{
    p: 3,                         // theme.spacing(3) = 24px
    bgcolor: "background.paper",  // theme.palette.background.paper
    borderRadius: 1,              // theme.shape.borderRadius * 1
    boxShadow: 3,                 // theme.shadows[3]
    width: { xs: "100%", md: "50%" }, // Responsive
    "&:hover": { boxShadow: 6 },
  }}
/>

Why good: Theme-aware shorthand properties, responsive without media queries

// BAD: Inline styles bypass theme
<Box style={{ padding: 24, backgroundColor: "#1976d2" }}>

Why bad: Hardcoded values, no theme consistency, no responsive support, no dark mode awareness

For callback syntax and advanced sx patterns, see [examples/styling.md](examples/styling.md).

Pattern 4: styled() API for Reusable Components

Use styled() when you need a reusable component with theme-aware styles. Prefer sx for one-off styles.