Learn-skills.dev web-ui-mui

Material UI component library patterns for React

install

source · Clone the upstream repo

git clone https://github.com/NeverSight/learn-skills.dev

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/NeverSight/learn-skills.dev "$T" && mkdir -p ~/.claude/skills && cp -r "$T/data/skills-md/agents-inc/skills/web-ui-mui" ~/.claude/skills/neversight-learn-skills-dev-web-ui-mui && rm -rf "$T"

manifest: data/skills-md/agents-inc/skills/web-ui-mui/SKILL.md

source content

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

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>

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.

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.

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.

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.

import { styled } from "@mui/material/styles";
import Card from "@mui/material/Card";

const HOVER_ELEVATION = 8;

const StyledCard = styled(Card)(({ theme }) => ({
  padding: theme.spacing(3),
  borderRadius: theme.shape.borderRadius * 2,
  "&:hover": { boxShadow: theme.shadows[HOVER_ELEVATION] },
  ...theme.applyStyles("dark", {
    backgroundColor: theme.palette.grey[900],
  }),
}));

export { StyledCard };

Why good: Reusable, theme-aware, dark mode handled with

applyStyles

For styled with custom props (

shouldForwardProp

), gradient buttons, and more, see examples/styling.md.

Pattern 5: Slots and SlotProps (v7 Standard)

In MUI v7,

slots

and

slotProps

are the standardized API for customizing component inner elements. The older

components

componentsProps

API is deprecated.

<Autocomplete
  slots={{ paper: Paper }}
  slotProps={{
    paper: { elevation: 8, sx: { borderRadius: 2 } },
    listbox: { sx: { maxHeight: 300 } },
  }}
  renderInput={(params) => <TextField {...params} label="Framework" />}
/>

Why good: Standardized API across all MUI components, replaces deprecated patterns

// BAD: Deprecated in v7
<Autocomplete componentsProps={{ paper: { elevation: 8 } }} />

For callback slotProps and advanced customization, see examples/form-inputs.md.

Pattern 6: Layout Components

MUI provides

Box

Stack

Grid

, and

Container

for layout. In v7,

Grid

is the former Grid2.

// Grid: 12-column responsive layout (v7 uses size prop)
const SIDEBAR_COLUMNS = 4;
const MAIN_COLUMNS = 8;

<Grid container spacing={3}>
  <Grid size={{ xs: 12, md: SIDEBAR_COLUMNS }}><Sidebar /></Grid>
  <Grid size={{ xs: 12, md: MAIN_COLUMNS }}><MainContent /></Grid>
</Grid>

// Stack: single-axis layout with consistent spacing
<Stack direction={{ xs: "column", sm: "row" }} spacing={2}>
  <Button variant="contained">Save</Button>
  <Button variant="outlined">Cancel</Button>
</Stack>

// Container: centered content with maxWidth
<Container maxWidth="lg" sx={{ py: 4 }}>{children}</Container>

When to use each: Box (flex/sx wrapper), Stack (single axis), Grid (12-column), Container (page centering)

For product card grids, dashboard layouts, and more, see examples/layout.md.

Pattern 7: TypeScript Theme Augmentation

Extend MUI's theme type system when adding custom palette colors or typography variants.

// theme-augmentation.d.ts
declare module "@mui/material/styles" {
  interface Palette {
    neutral: Palette["primary"];
  }
  interface PaletteOptions {
    neutral?: PaletteOptions["primary"];
  }
}
declare module "@mui/material/Button" {
  interface ButtonPropsColorOverrides {
    neutral: true;
  }
}

Then use in theme and components:

const theme = createTheme({
  palette: { neutral: { main: "#64748b", contrastText: "#fff" } },
});
<Button color="neutral" variant="contained">Neutral</Button>

Why good: Full type safety, IDE autocomplete for custom colors/variants

For complete augmentation with typography variants, see examples/core.md.

Pattern 8: Next.js App Router Integration

MUI requires

AppRouterCacheProvider

from

@mui/material-nextjs

for proper SSR style injection.

// app/layout.tsx
import { AppRouterCacheProvider } from "@mui/material-nextjs/v15-appRouter";
import { ThemeProvider } from "@mui/material/styles";
import CssBaseline from "@mui/material/CssBaseline";

function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <AppRouterCacheProvider>
          <ThemeProvider theme={theme}>
            <CssBaseline />
            {children}
          </ThemeProvider>
        </AppRouterCacheProvider>
      </body>
    </html>
  );
}

export default RootLayout; // Next.js requires default export for layouts

Why good: Prevents style hydration mismatches, CSS layers enable predictable specificity with utility-first CSS

For CSS layers integration and Vite setup, see examples/core.md.

</patterns>

Performance Optimization

Import Optimization

// GOOD: Path imports -- fast in development
import Button from "@mui/material/Button";
import DeleteIcon from "@mui/icons-material/Delete";

// BAD: Barrel imports -- 6x slower dev startup
import { Button } from "@mui/material";
import { Delete } from "@mui/icons-material";

Path imports skip barrel file parsing.

@mui/icons-material

has 2000+ modules -- barrel imports force parsing all of them.

Exception: Next.js 13.5+ auto-optimizes via

optimizePackageImports

Memoize Expensive Props

// GOOD: Columns outside component (stable reference)
const columns: GridColDef[] = [
  { field: "id", headerName: "ID", width: 90 },
];
function Table({ rows }: { rows: User[] }) {
  return <DataGrid rows={rows} columns={columns} />;
}

// BAD: Inline columns cause re-render every parent render

Stable Slot References

// GOOD: Defined outside render
const CustomPaper = (props: PaperProps) => <Paper {...props} elevation={8} />;
<Autocomplete slots={{ paper: CustomPaper }} />

// BAD: Inline function causes remount every render
<Autocomplete slots={{ paper: (props) => <Paper {...props} /> }} />

ESLint Rule for Import Enforcement

{
  "rules": {
    "no-restricted-imports": [
      "error",
      {
        "patterns": [
          {
            "regex": "^@mui/[^/]+$",
            "message": "Use path imports: import Button from '@mui/material/Button'"
          }
        ]
      }
    ]
  }
}

</performance>

<decision_framework>

Decision Framework

Styling Approach

How many places will this style be used?
+-- One place --> sx prop (inline, theme-aware)
+-- Multiple places (same type) --> styled() (reusable, typed)
+-- All instances of a component --> theme.components (global override)
+-- Customize inner elements --> slots/slotProps

Layout Component Selection

What kind of layout?
+-- Single axis (row or column) --> Stack
+-- 12-column grid --> Grid
+-- Centered page content --> Container
+-- Flexible box with sx --> Box
+-- Both axes + complex --> Grid (nested)

Component vs Custom Build

Does MUI have this component?
+-- YES --> Use it
|   +-- Minor style changes --> sx prop
|   +-- Structural changes --> slots/slotProps
|   +-- Completely different behavior --> Build custom
+-- NO --> Build custom
    +-- Simple interaction --> Base HTML + sx
    +-- Complex interaction --> Consider a headless component library

Color Scheme Strategy

Do you need dark mode?
+-- YES --> Use colorSchemes in createTheme
|   +-- System preference only --> cssVariables: true
|   +-- Manual toggle --> useColorScheme hook
|   +-- Both --> colorSchemeSelector: "data" + useColorScheme
+-- NO --> Single palette in createTheme

MUI X Component Selection

What data display do you need?
+-- Tabular data
|   +-- Simple (< 100 rows, no editing) --> Table component
|   +-- Complex (sorting, filtering, pagination) --> DataGrid
|   +-- Large dataset (100K+ rows) --> DataGridPro (virtualized)
+-- Date/time input --> DatePicker / DateTimePicker
+-- Charts --> MUI X Charts
+-- Tree structure --> TreeView

</decision_framework>

Integration Notes

React 19: Full compatibility in MUI v7.

SSR Frameworks: Use

@mui/material-nextjs

with

AppRouterCacheProvider

for Next.js App Router. See examples/core.md for setup.

CSS Layers: Enable with

enableCssLayer

to integrate with utility-first CSS frameworks. Allows predictable specificity ordering.

Form Libraries: MUI

TextField

works with any form library via

inputRef

for registration or controlled

value

onChange

props. Map validation errors to

helperText

and

error

props.

Styling Engine: Emotion is the default and only production-ready engine.

@emotion/react

and

@emotion/styled

are required peer dependencies.

Package Ecosystem:

Package	Purpose	Version
`@mui/material`	Core components (Button, TextField, etc.)	v7.x
`@mui/system`	sx prop, styled(), ThemeProvider	v7.x
`@mui/icons-material`	2000+ Material Design icons	v7.x
`@mui/x-data-grid`	DataGrid (free tier)	v8.x
`@mui/x-data-grid-pro`	DataGrid Pro (sorting, filtering, etc.)	v8.x
`@mui/x-date-pickers`	DatePicker, TimePicker	v8.x
`@mui/x-charts`	Bar, Line, Pie, Scatter charts	v8.x
`@mui/x-tree-view`	TreeView component	v8.x
`@mui/material-nextjs`	Next.js SSR integration	v7.x
`@emotion/react`	Required peer dependency	v11.x
`@emotion/styled`	Required peer dependency	v11.x

</integration>

<red_flags>

RED FLAGS

High Priority Issues:

Using

theme.palette.mode === 'dark'

for conditional styles (causes SSR flicker -- use

theme.applyStyles('dark', {...})

)

Missing
```
ThemeProvider
```
wrapper (components render with MUI defaults instead of your design tokens)
Using barrel imports from
```
@mui/material
```
or
```
@mui/icons-material
```
(6x slower dev builds)
Inline object/function definitions in
```
slots
```
prop (causes component remount every render)

Medium Priority Issues:

Using deprecated
```
components
```
/
```
componentsProps
```
instead of
```
slots
```
/
```
slotProps
```
(removed in future versions)
Using
```
GridLegacy
```
instead of the new
```
Grid
```
component with
```
size
```
prop
Hardcoding colors/spacing instead of using theme tokens (
```
#1976d2
```
vs
```
primary.main
```
)
Using
```
style
```
prop instead of
```
sx
```
(bypasses theme, no responsive support)
Deep importing beyond one level:
```
@mui/material/styles/createTheme
```
(broken in v7 ESM)

Common Mistakes:

Forgetting
```
CssBaseline
```
(inconsistent cross-browser baseline styles)
Not memoizing DataGrid
```
columns
```
array (causes unnecessary re-renders)
Using
```
@mui/lab
```
for graduated components (Alert, Skeleton, etc. are now in
```
@mui/material
```
)
Missing TypeScript augmentation for custom palette colors (no autocomplete, type errors at usage)
Setting
```
zIndex
```
manually on MUI components (conflicts with MUI's z-index scale)

Gotchas & Edge Cases:

MUI components are client-only -- they require
```
'use client'
```
in Next.js App Router pages, not just layout
```
sx
```
prop arrays merge styles left-to-right; later items override earlier ones (useful for conditional styles)
```
spacing
```
theme value is a multiplier, not pixels:
```
spacing(2)
```
=
```
2 * 8px
```
=
```
16px
```
by default
```
Grid
```
```
size
```
prop in v7 replaces
```
xs
```
/
```
sm
```
/
```
md
```
/
```
lg
```
/
```
xl
```
individual props from Grid2
```
TextField
```
is a composed component (Input + InputLabel + FormHelperText) -- use
```
slotProps.input
```
to target the actual input element
```
Dialog
```
```
TransitionProps
```
must not remount the Transition component -- keep it stable between renders
```
useMediaQuery
```
returns
```
false
```
during SSR -- design for mobile-first and handle the hydration mismatch
```
createTheme
```
is not tree-shakeable -- a large theme config doesn't increase bundle, but unused components still need tree shaking via path imports

</red_flags>

<critical_reminders>

CRITICAL REMINDERS

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)

Failure to follow these rules will cause SSR flickering, degraded dev performance, and deprecated API usage.

</critical_reminders>