Item ``` ### Icons ```tsx // SVG icon components (recommended) import DeleteIcon from '@mui/icons-material/Delete'; import DeleteOutlinedIcon from '@mui/icons-material/DeleteOutlined'; import DeleteRoundedIcon from '@mui/icons-material/DeleteRounded'; import DeleteSharpIcon from '@mui/icons-material/DeleteSharp'; import DeleteTwoToneIcon from '@mui/icons-material/DeleteTwoTone'; ``` Each icon is available in 5 variants: Filled (default), Outlined, Rounded, Sharp, and TwoTone. Over 2,100 icons are available in `@mui/icons-material`. ### Localization MUI components that render text (e.g., TablePagination, Alert) support localization: ```tsx import { createTheme, ThemeProvider } from '@mui/material/styles'; import { frFR } from '@mui/material/locale'; const theme = createTheme({}, frFR); // French locale ``` Available locales include: `amET`, `arEG`, `arSA`, `bnBD`, `csCZ`, `daDK`, `deDE`, `elGR`, `enUS`, `esES`, `etEE`, `faIR`, `fiFI`, `frFR`, `heIL`, `hiIN`, `hrHR`, `huHU`, `hyAM`, `idID`, `isIS`, `itIT`, `jaJP`, `khKH`, `koKR`, `kuCKB`, `mkMK`, `msMY`, `nbNO`, `nlNL`, `plPL`, `ptBR`, `ptPT`, `roRO`, `ruRU`, `skSK`, `srRS`, `svSE`, `thTH`, `trTR`, `ukUA`, `urPK`, `viVN`, `zhCN`, `zhHK`, `zhTW`, and more. --- ## 5. Common Tasks ### Build a Login Form ```tsx import { Box, TextField, Button, Typography, Paper, Alert } from '@mui/material'; function LoginForm() { const [error, setError] = React.useState(''); const handleSubmit = (event: React.FormEvent) => { event.preventDefault(); const data = new FormData(event.currentTarget as HTMLFormElement); const email = data.get('email') as string; const password = data.get('password') as string; if (!email || !password) { setError('All fields are required'); return; } // Submit login }; return ( Sign In {error && {error}} ); } ``` ### Create a Responsive Navigation Drawer ```tsx import { AppBar, Toolbar, Typography, IconButton, Drawer, List, ListItem, ListItemIcon, ListItemText, useMediaQuery, useTheme } from '@mui/material'; import MenuIcon from '@mui/icons-material/Menu'; import HomeIcon from '@mui/icons-material/Home'; import SettingsIcon from '@mui/icons-material/Settings'; function ResponsiveNav() { const [open, setOpen] = React.useState(false); const theme = useTheme(); const isDesktop = useMediaQuery(theme.breakpoints.up('md')); const drawerContent = ( ); return ( <> {!isDesktop && ( setOpen(true)}> )} My App setOpen(false)} > {drawerContent} ); } ``` ### Build a Data Table with Sorting and Pagination ```tsx import { Table, TableBody, TableCell, TableContainer, TableHead, TableRow, TablePagination, TableSortLabel, Paper } from '@mui/material'; function DataTable({ rows }) { const [page, setPage] = React.useState(0); const [rowsPerPage, setRowsPerPage] = React.useState(10); const [orderBy, setOrderBy] = React.useState('name'); const [order, setOrder] = React.useState<'asc' | 'desc'>('asc'); const handleSort = (property: string) => { const isAsc = orderBy === property && order === 'asc'; setOrder(isAsc ? 'desc' : 'asc'); setOrderBy(property); }; const sortedRows = [...rows].sort((a, b) => { const cmp = a[orderBy] < b[orderBy] ? -1 : 1; return order === 'asc' ? cmp : -cmp; }); return ( handleSort('name')} > Name Value {sortedRows .slice(page * rowsPerPage, page * rowsPerPage + rowsPerPage) .map((row) => ( {row.name} {row.value} ))}

setPage(p)} rowsPerPage={rowsPerPage} onRowsPerPageChange={(e) => { setRowsPerPage(parseInt(e.target.value)); setPage(0); }} /> ); } ``` ### Create a Confirmation Dialog ```tsx import { Dialog, DialogTitle, DialogContent, DialogContentText, DialogActions, Button } from '@mui/material'; function ConfirmDialog({ open, onClose, onConfirm, title, message }) { return ( ); } ``` ### Display a Notification Snackbar ```tsx import { Snackbar, Alert, Button } from '@mui/material'; function NotificationExample() { const [open, setOpen] = React.useState(false); return ( <> setOpen(false)} anchorOrigin={{ vertical: 'bottom', horizontal: 'center' }} > setOpen(false)} severity="success" variant="filled"> Changes saved successfully! ); } ``` ### Build a Multi-Step Form (Stepper) ```tsx import { Stepper, Step, StepLabel, Button, Typography, Box } from '@mui/material'; const steps = ['Account Details', 'Personal Info', 'Review']; function MultiStepForm() { const [activeStep, setActiveStep] = React.useState(0); return ( {steps.map((label) => ( {label} ))} Step {activeStep + 1}: {steps[activeStep]} ); } ``` ### Implement Async Search with Autocomplete ```tsx import Autocomplete from '@mui/material/Autocomplete'; import TextField from '@mui/material/TextField'; import CircularProgress from '@mui/material/CircularProgress'; function AsyncSearch() { const [open, setOpen] = React.useState(false); const [options, setOptions] = React.useState([]); const [loading, setLoading] = React.useState(false); const handleInputChange = async (_, value) => { if (value.length < 2) return; setLoading(true); const results = await fetchResults(value); setOptions(results); setLoading(false); }; return ( setOpen(true)} onClose={() => setOpen(false)} onInputChange={handleInputChange} options={options} loading={loading} getOptionLabel={(option) => option.name} renderInput={(params) => ( {loading ? : null} {params.InputProps.endAdornment} ), }, }} /> )} /> ); } ``` > [!WARNING] > Autocomplete can experience performance degradation with very large datasets (~1 million items, GitHub issue #33487). For large datasets, implement virtualization via the `slots.listbox` prop or use server-side filtering to limit the option set. ### Apply Conditional Styles with Theme ```tsx import { styled } from '@mui/material/styles'; import Paper from '@mui/material/Paper'; const StyledCard = styled(Paper)(({ theme }) => ({ padding: theme.spacing(3), borderRadius: theme.shape.borderRadius, [theme.breakpoints.down('sm')]: { padding: theme.spacing(1), }, ...theme.applyStyles('dark', { backgroundColor: theme.palette.grey[900], }), })); ``` ### Use CSS Variables Theming with Mode Toggle ```tsx import { Experimental_CssVarsProvider as CssVarsProvider, useColorScheme, } from '@mui/material/styles'; import Button from '@mui/material/Button'; function ThemeToggle() { const { mode, setMode } = useColorScheme(); return ( ); } function App() { return ( ); } ``` ### Use Lab Tabs with Context ```tsx import { TabContext, TabList, TabPanel } from '@mui/lab'; import { Tab, Box } from '@mui/material'; function TabbedView() { const [value, setValue] = React.useState('1'); return ( setValue(v)}> Overview content Details content Settings content ); } ``` ### Create a Loading Button ```tsx import LoadingButton from '@mui/lab/LoadingButton'; import SaveIcon from '@mui/icons-material/Save'; } variant="contained" onClick={handleSave} > Save ``` ### Build a Timeline ```tsx import { Timeline, TimelineItem, TimelineSeparator, TimelineConnector, TimelineContent, TimelineDot, TimelineOppositeContent, } from '@mui/lab'; 9:30 am Eat breakfast 10:00 am Start work ``` ### Build a Masonry Layout ```tsx import Masonry from '@mui/lab/Masonry'; import Paper from '@mui/material/Paper'; {items.map((item) => ( {item.content} ))} ``` --- ## 6. Troubleshooting ### Diagnostic Decision Tree ```text Component not rendering? ├── Missing ThemeProvider? → Wrap app with ThemeProvider ├── Import error? → Check import path (named vs default) ├── React version mismatch? → Run `npm ls react`, ensure single version └── Emotion not installed? → Install @emotion/react @emotion/styled Styles not applying? ├── Using sx on non-MUI element? → Wrap with ├── CSS specificity issue? → Check injection order, use StyledEngineProvider ├── SSR hydration mismatch? → Ensure Emotion cache configured for SSR └── Theme not reaching component? → Verify ThemeProvider placement Component behaving unexpectedly? ├── Controlled/uncontrolled warning? → Provide both value + onChange, or neither ├── Autocomplete issues? → See Autocomplete-specific entries below └── Modal/Dialog not opening? → Check `open` prop state management ``` ### Error: Autocomplete options DOM present when empty in `freeSolo` mode **Cause:** In `freeSolo` mode, the options listbox DOM node remains present even when there are no options, causing layout or styling issues (GitHub issue #40843). **Solution:** ```tsx ``` **Prevention:** Monitor this issue for a future fix in MUI core. ### Error: Autocomplete scroll resets when appending options **Cause:** When new options are appended to the list after the user scrolls to the bottom (infinite scroll pattern), the list resets to the top (GitHub issue #40250). **Solution:** Use a virtualized listbox via the `slots.listbox` prop and manage scroll position manually. **Prevention:** Consider server-side pagination rather than client-side infinite scroll for large datasets. ### Error: Autocomplete highlights wrong item after scroll + Enter **Cause:** Visual highlight and actual highlighted index can go out of sync in `multiple` mode when the popup is reopened (GitHub issue #48177), or when scrolling and pressing Enter quickly (GitHub issue #46718). **Solution:** Use `disableListWrap` or implement custom keyboard handling. For issue #46718 (closed), update to the latest MUI version. ### Error: Highlighted index not reset when options change **Cause:** When the Autocomplete options array changes but keeps the same length, the highlighted index is not reset, pointing to a stale item (GitHub issue #40184). **Solution:** Key your Autocomplete or force a remount when the logical option set changes. ### Error: Keyboard scrolling broken in fullscreen Dialog **Cause:** Fullscreen dialogs may not respond to keyboard scrolling correctly (GitHub issue #42989, closed/fixed). **Solution:** Update to the latest MUI version. ### Error: Styles from `sx` prop not applying in production **Cause:** CSS injection order differs between development and production when Emotion's default cache prepends styles. **Solution:** ```tsx import { StyledEngineProvider } from '@mui/material/styles'; ``` **Prevention:** Always use `StyledEngineProvider` with `injectFirst` if you mix MUI styles with custom CSS or Tailwind. ### Error: NVDA screen reader does not announce Select helper text **Cause:** The Select component's helper text is not programmatically associated via `aria-describedby` for NVDA users (GitHub issue #19886, open). **Solution:** Manually add `aria-describedby` linking the Select to its helper text element: ```tsx Label Help text ``` ### Error: ChromeVox cannot navigate into Dialog content **Cause:** ChromeVox linear navigation cannot enter Dialog content in certain configurations (GitHub issue #42622, open). **Solution:** Ensure the Dialog has `aria-labelledby` pointing to `DialogTitle` and `aria-describedby` pointing to `DialogContent`. > [!CAUTION] > Accessibility issues with screen readers are actively tracked. Test your application with multiple assistive technologies (NVDA, JAWS, VoiceOver, ChromeVox) to catch interaction gaps early. ### Error: ListSubheader does not match dark-mode Paper background **Cause:** `ListSubheader` uses a hardcoded background that does not respond to Paper's elevated dark-mode background (GitHub issue #30468). **Solution:** ```tsx Section Header ``` ### Error: TimelineItem extra space from `::before` pseudo-element **Cause:** `TimelineItem` renders a `::before` pseudo-element for opposite content even when no opposite content exists (GitHub issue #46639, closed/fixed). **Solution:** Update to the latest MUI version, or manually override: ```tsx ``` ### Warning: `A component is changing the default/controlled state` **Cause:** Switching between controlled (`value` prop) and uncontrolled (no `value` prop) modes, or changing `defaultValue` after mount. **Solution:** Always provide both `value` and `onChange` for controlled mode, or neither for uncontrolled. Never set `value` to `undefined` for a controlled component — use empty string `''` or `null` instead. > [!WARNING] > Setting `value={undefined}` silently switches a controlled component to uncontrolled mode. This is a common source of bugs. ### Error: `freeSolo` Autocomplete value changes to first matching item **Cause:** When editing a `freeSolo` value that partially matches an existing option, the value snaps to that option (GitHub issue #27137, closed/fixed). **Solution:** Update to the latest MUI version. ### Error: Autocomplete value changes on mouse hover **Cause:** In older versions, hovering over options could unexpectedly change the selected value (GitHub issue #20602, closed/fixed, 27 comments). **Solution:** Update to the latest MUI version. --- ## 7. FAQ **Q: Can I use MUI with React 17?** Yes. MUI v9 supports React 17, 18, and 19. The peer dependency is `react ^17.0.0 || ^18.0.0 || ^19.0.0`. **Q: How do I reduce my bundle size?** Use path imports (`import Button from '@mui/material/Button'` instead of `import { Button } from '@mui/material'`). Ensure your bundler supports tree-shaking and that `sideEffects: false` is respected. For icons, import only the icons you use — the `@mui/icons-material` package contains 2,100+ icons across 5 style variants. **Q: How do I override a component's styles without `sx`?** Three options: 1. **Theme style overrides** — apply globally via `createTheme({ components: { MuiButton: { styleOverrides: { root: {...} }}}})` 2. **`styled()` API** — create a styled variant: `const MyButton = styled(Button)({ ... })` 3. **CSS class overrides** — target generated class names (e.g., `.MuiButton-root`) **Q: How do I change the default variant for all TextFields?** Use theme default props: ```tsx createTheme({ components: { MuiTextField: { defaultProps: { variant: 'filled' } }, }, }) ``` **Q: What is the difference between `@mui/lab` and `@mui/material`?** `@mui/lab` is the incubator for components not yet stable enough for the core library. Components graduate from lab to material when their API stabilizes. Currently in lab: LoadingButton, Masonry, Timeline components, TabContext/TabList/TabPanel. Date pickers have moved to the separate `@mui/x-date-pickers` package. **Q: How do I migrate from MUI v5 to v9?** Use the automated codemods sequentially: ```bash npx @mui/codemod v6.0.0/all npx @mui/codemod v7.0.0/all npx @mui/codemod v9.0.0/system-props ``` Use `--dry` to preview changes first. Each version has specific codemods for breaking changes (grid props, theme color functions, system props, etc.). **Q: Does MUI support server-side rendering?** Yes. For Next.js, install `@mui/material-nextjs` which handles Emotion cache integration automatically. For Express or custom SSR, use `@emotion/server` to extract critical CSS. See the Installation section for framework-specific setup. **Q: How do I create a custom palette color?** Extend the palette in your theme: ```tsx const theme = createTheme({ palette: { customColor: { main: '#ff5722', light: '#ff8a50', dark: '#c41c00', contrastText: '#fff', }, }, }); ``` Then use it: `