0
# MUI Integration
1

2
TSS-React provides specialized integration for Material-UI applications with built-in theme support, style overrides compatibility, and seamless migration from @material-ui/core v4. The integration includes pre-configured instances and plugins for MUI theme systems.
3

4
## Capabilities
5

6
### Pre-configured MUI Instances
7

8
Ready-to-use TSS, makeStyles, and withStyles instances with MUI theme integration.
9

10
```typescript { .api }
11
/**
12
 * Pre-configured TSS instance with MUI theme context and plugin support
13
 */
14
const tss: Tss<{ theme: Theme }, {}, never, MuiThemeStyleOverridesPluginParams, never>;
15

16
/**
17
 * Pre-configured makeStyles function with MUI theme
18
 */
19
const makeStyles: <Params = void, RuleNameSubsetReferencableInNestedSelectors extends string = never>(
20
  params?: { name?: string | Record<string, unknown>; uniqId?: string }
21
) => MakeStylesHook<Theme, Params, RuleNameSubsetReferencableInNestedSelectors>;
22

23
/**
24
 * Pre-configured withStyles HOC with MUI theme
25
 */
26
const withStyles: <Component, Props, CssObjectByRuleName>(
27
  Component: Component,
28
  cssObjectByRuleNameOrGetCssObjectByRuleName: 
29
    | CssObjectByRuleName 
30
    | ((theme: Theme, props: Props, classes: Record<string, string>) => CssObjectByRuleName)
31
) => ComponentType<Props>;
32

33
/**
34
 * Pre-configured useStyles hook with MUI theme context
35
 */
36
const useStyles: UseStyles<{ theme: Theme }, {}, string, MuiThemeStyleOverridesPluginParams>;
37

38
interface Theme {
39
  palette: any;
40
  typography: any;
41
  spacing: (...args: any[]) => any;
42
  breakpoints: any;
43
  shadows: any;
44
  shape: any;
45
  transitions: any;
46
  zIndex: any;
47
  [key: string]: any;
48
}
49
```
50

51
**Usage Examples:**
52

53
```typescript
54
import { tss, makeStyles, withStyles, useStyles } from "tss-react/mui";
55

56
// Using pre-configured TSS instance
57
const useComponentStyles = tss.create(({ theme }) => ({
58
  root: {
59
    backgroundColor: theme.palette.background.paper,
60
    padding: theme.spacing(2),
61
    borderRadius: theme.shape.borderRadius
62
  },
63
  title: {
64
    color: theme.palette.primary.main,
65
    fontSize: theme.typography.h5.fontSize,
66
    fontWeight: theme.typography.fontWeightBold
67
  }
68
}));
69

70
// Using pre-configured makeStyles
71
const useMakeStyles = makeStyles()(theme => ({
72
  container: {
73
    maxWidth: theme.breakpoints.values.md,
74
    margin: "0 auto",
75
    padding: theme.spacing(0, 2)
76
  }
77
}));
78

79
// Using pre-configured withStyles
80
const StyledButton = withStyles(
81
  ({ children, classes }: { children: React.ReactNode; classes?: { root?: string } }) => (
82
    <button className={classes?.root}>{children}</button>
83
  ),
84
  theme => ({
85
    root: {
86
      backgroundColor: theme.palette.primary.main,
87
      color: theme.palette.primary.contrastText,
88
      padding: theme.spacing(1, 2),
89
      border: "none",
90
      borderRadius: theme.shape.borderRadius,
91
      "&:hover": {
92
        backgroundColor: theme.palette.primary.dark
93
      }
94
    }
95
  })
96
);
97

98
function MyMuiComponent() {
99
  const { classes } = useComponentStyles();
100
  const { classes: layoutClasses } = useMakeStyles();
101
  
102
  return (
103
    <div className={layoutClasses.container}>
104
      <div className={classes.root}>
105
        <h1 className={classes.title}>MUI Integration Example</h1>
106
        <StyledButton>Click me</StyledButton>
107
      </div>
108
    </div>
109
  );
110
}
111
```
112

113
### MUI Theme Style Overrides Plugin
114

115
Plugin system for integrating with MUI's theme style overrides mechanism, enabling component customization through theme configuration.
116

117
```typescript { .api }
118
/**
119
 * Plugin for MUI theme style overrides integration
120
 * @param params - Plugin parameters including classes, theme, and MUI-specific options
121
 * @returns Processed classes with theme overrides applied
122
 */
123
const useMuiThemeStyleOverridesPlugin: UsePlugin<
124
  { theme: MuiThemeLike },
125
  MuiThemeStyleOverridesPluginParams
126
> = (params: {
127
  classes: Record<string, string>;
128
  theme: MuiThemeLike;
129
  muiStyleOverridesParams?: MuiThemeStyleOverridesPluginParams;
130
  css: Css;
131
  cx: Cx;
132
  name?: string;
133
}) => Record<string, string>;
134

135
interface MuiThemeStyleOverridesPluginParams {
136
  muiStyleOverridesParams?: {
137
    props: Record<string, unknown>;
138
    ownerState?: Record<string, unknown>;
139
  };
140
}
141

142
interface MuiThemeLike {
143
  components?: Record<string, {
144
    styleOverrides?: Record<string, any>;
145
  }>;
146
}
147
```
148

149
**Usage Examples:**
150

151
```typescript
152
import { createTss } from "tss-react";
153
import { useTheme } from "@mui/material/styles";
154
import { useMuiThemeStyleOverridesPlugin } from "tss-react/mui";
155

156
// Manual setup with plugin
157
const { tss } = createTss({
158
  useContext: () => {
159
    const theme = useTheme();
160
    return { theme };
161
  },
162
  usePlugin: useMuiThemeStyleOverridesPlugin
163
});
164

165
// Component with theme overrides support
166
const useCardStyles = tss
167
  .withName("MyCard")
168
  .withParams<{ variant: "outlined" | "elevated" }>()
169
  .create(({ theme }, { variant }) => ({
170
    root: {
171
      backgroundColor: theme.palette.background.paper,
172
      borderRadius: theme.shape.borderRadius,
173
      padding: theme.spacing(2),
174
      ...(variant === "outlined" && {
175
        border: `1px solid ${theme.palette.divider}`
176
      }),
177
      ...(variant === "elevated" && {
178
        boxShadow: theme.shadows[4]
179
      })
180
    },
181
    header: {
182
      borderBottom: `1px solid ${theme.palette.divider}`,
183
      paddingBottom: theme.spacing(1),
184
      marginBottom: theme.spacing(2)
185
    },
186
    content: {
187
      color: theme.palette.text.secondary
188
    }
189
  }));
190

191
// Theme configuration with style overrides
192
const theme = createTheme({
193
  components: {
194
    MyCard: {
195
      styleOverrides: {
196
        root: {
197
          // These styles will be merged with component styles
198
          transition: "all 0.3s ease",
199
          "&:hover": {
200
            transform: "translateY(-2px)"
201
          }
202
        },
203
        header: {
204
          fontWeight: 600,
205
          textTransform: "uppercase"
206
        }
207
      }
208
    }
209
  }
210
});
211

212
function MyCard({ 
213
  variant, 
214
  title, 
215
  children 
216
}: { 
217
  variant: "outlined" | "elevated";
218
  title: string;
219
  children: React.ReactNode;
220
}) {
221
  const { classes } = useCardStyles({ variant });
222
  
223
  return (
224
    <div className={classes.root}>
225
      <div className={classes.header}>{title}</div>
226
      <div className={classes.content}>{children}</div>
227
    </div>
228
  );
229
}
230
```
231

232
### MUI Theme Integration Patterns
233

234
#### Responsive Design with Breakpoints
235

236
```typescript
237
import { tss } from "tss-react/mui";
238

239
const useResponsiveStyles = tss.create(({ theme }) => ({
240
  container: {
241
    padding: theme.spacing(1),
242
    [theme.breakpoints.up("sm")]: {
243
      padding: theme.spacing(2)
244
    },
245
    [theme.breakpoints.up("md")]: {
246
      padding: theme.spacing(3),
247
      maxWidth: theme.breakpoints.values.lg,
248
      margin: "0 auto"
249
    }
250
  },
251
  grid: {
252
    display: "grid",
253
    gap: theme.spacing(1),
254
    gridTemplateColumns: "1fr",
255
    [theme.breakpoints.up("sm")]: {
256
      gridTemplateColumns: "repeat(2, 1fr)",
257
      gap: theme.spacing(2)
258
    },
259
    [theme.breakpoints.up("lg")]: {
260
      gridTemplateColumns: "repeat(3, 1fr)",
261
      gap: theme.spacing(3)
262
    }
263
  }
264
}));
265
```
266

267
#### Theme Palette and Typography Integration
268

269
```typescript
270
import { tss } from "tss-react/mui";
271

272
const useThemedStyles = tss
273
  .withParams<{ 
274
    severity: "info" | "warning" | "error" | "success";
275
    size: "small" | "medium" | "large";
276
  }>()
277
  .create(({ theme }, { severity, size }) => {
278
    const palette = theme.palette[severity];
279
    const typography = {
280
      small: theme.typography.body2,
281
      medium: theme.typography.body1,
282
      large: theme.typography.h6
283
    }[size];
284
    
285
    return {
286
      alert: {
287
        backgroundColor: palette.light,
288
        color: palette.contrastText,
289
        border: `1px solid ${palette.main}`,
290
        borderRadius: theme.shape.borderRadius,
291
        padding: theme.spacing(1, 2),
292
        fontSize: typography.fontSize,
293
        fontWeight: typography.fontWeight,
294
        lineHeight: typography.lineHeight
295
      },
296
      icon: {
297
        marginRight: theme.spacing(1),
298
        color: palette.main
299
      }
300
    };
301
  });
302
```
303

304
#### Animation and Transitions
305

306
```typescript
307
import { tss } from "tss-react/mui";
308

309
const useAnimatedStyles = tss
310
  .withParams<{ expanded: boolean; loading: boolean }>()
311
  .create(({ theme }, { expanded, loading }) => ({
312
    expandableCard: {
313
      backgroundColor: theme.palette.background.paper,
314
      borderRadius: theme.shape.borderRadius,
315
      overflow: "hidden",
316
      transition: theme.transitions.create(
317
        ["height", "box-shadow"],
318
        {
319
          duration: theme.transitions.duration.standard,
320
          easing: theme.transitions.easing.easeInOut
321
        }
322
      ),
323
      height: expanded ? "auto" : 60,
324
      boxShadow: expanded ? theme.shadows[8] : theme.shadows[2]
325
    },
326
    loadingSpinner: {
327
      animation: loading ? `$spin 1s linear infinite` : "none",
328
      color: theme.palette.primary.main
329
    },
330
    "@keyframes spin": {
331
      "0%": { transform: "rotate(0deg)" },
332
      "100%": { transform: "rotate(360deg)" }
333
    }
334
  }));
335
```
336

337
### Migration from Material-UI v4
338

339
#### Complete Migration Example
340

341
```typescript
342
// Before (Material-UI v4)
343
import { makeStyles, withStyles } from "@material-ui/core/styles";
344

345
const useStyles = makeStyles(theme => ({
346
  root: {
347
    backgroundColor: theme.palette.background.paper,
348
    padding: theme.spacing(2)
349
  }
350
}));
351

352
const StyledComponent = withStyles(theme => ({
353
  root: {
354
    color: theme.palette.primary.main
355
  }
356
}))(({ classes }) => <div className={classes.root}>Content</div>);
357

358
// After (TSS-React MUI)
359
import { makeStyles, withStyles } from "tss-react/mui";
360

361
const useStyles = makeStyles()(theme => ({
362
  root: {
363
    backgroundColor: theme.palette.background.paper,
364
    padding: theme.spacing(2)
365
  }
366
}));
367

368
const StyledComponent = withStyles(
369
  ({ classes }: { classes?: { root?: string } }) => (
370
    <div className={classes?.root}>Content</div>
371
  ),
372
  theme => ({
373
    root: {
374
      color: theme.palette.primary.main
375
    }
376
  })
377
);
378
```
379

380
#### Theme Provider Setup
381

382
```typescript
383
import { ThemeProvider, createTheme } from "@mui/material/styles";
384
import CssBaseline from "@mui/material/CssBaseline";
385

386
const theme = createTheme({
387
  palette: {
388
    mode: "light",
389
    primary: {
390
      main: "#1976d2"
391
    },
392
    secondary: {
393
      main: "#dc004e"
394
    }
395
  },
396
  components: {
397
    // Style overrides work automatically with TSS-React
398
    MuiButton: {
399
      styleOverrides: {
400
        root: {
401
          textTransform: "none"
402
        }
403
      }
404
    }
405
  }
406
});
407

408
function App() {
409
  return (
410
    <ThemeProvider theme={theme}>
411
      <CssBaseline />
412
      <MyStyledComponents />
413
    </ThemeProvider>
414
  );
415
}
416
```
417

418
### Advanced MUI Integration
419

420
#### Custom Theme Extensions
421

422
```typescript
423
declare module "@mui/material/styles" {
424
  interface Theme {
425
    custom: {
426
      gradients: {
427
        primary: string;
428
        secondary: string;
429
      };
430
    };
431
  }
432
  
433
  interface ThemeOptions {
434
    custom?: {
435
      gradients?: {
436
        primary?: string;
437
        secondary?: string;
438
      };
439
    };
440
  }
441
}
442

443
const theme = createTheme({
444
  custom: {
445
    gradients: {
446
      primary: "linear-gradient(45deg, #FE6B8B 30%, #FF8E53 90%)",
447
      secondary: "linear-gradient(45deg, #2196F3 30%, #21CBF3 90%)"
448
    }
449
  }
450
});
451

452
const useCustomThemeStyles = tss.create(({ theme }) => ({
453
  gradientButton: {
454
    background: theme.custom.gradients.primary,
455
    color: "white",
456
    border: "none",
457
    borderRadius: theme.shape.borderRadius,
458
    padding: theme.spacing(1, 3),
459
    cursor: "pointer",
460
    transition: theme.transitions.create("transform"),
461
    "&:hover": {
462
      transform: "scale(1.05)"
463
    }
464
  }
465
}));
466
```
467

468
#### Integration with MUI Components
469

470
```typescript
471
import { Button, Card, CardContent, Typography } from "@mui/material";
472
import { tss } from "tss-react/mui";
473

474
const useIntegratedStyles = tss.create(({ theme }) => ({
475
  styledCard: {
476
    // Enhancing MUI Card component
477
    background: `linear-gradient(135deg, ${theme.palette.primary.light} 0%, ${theme.palette.primary.main} 100%)`,
478
    color: theme.palette.primary.contrastText,
479
    "& .MuiCardContent-root": {
480
      padding: theme.spacing(3)
481
    }
482
  },
483
  customButton: {
484
    // Custom styling that complements MUI Button
485
    marginTop: theme.spacing(2),
486
    borderRadius: theme.spacing(3),
487
    textTransform: "none",
488
    fontWeight: theme.typography.fontWeightBold
489
  }
490
}));
491

492
function IntegratedComponent() {
493
  const { classes } = useIntegratedStyles();
494
  
495
  return (
496
    <Card className={classes.styledCard}>
497
      <CardContent>
498
        <Typography variant="h5" component="h2">
499
          Custom Styled Card
500
        </Typography>
501
        <Typography variant="body2">
502
          This card combines MUI components with TSS-React custom styling.
503
        </Typography>
504
        <Button 
505
          variant="contained" 
506
          color="secondary"
507
          className={classes.customButton}
508
        >
509
          Learn More
510
        </Button>
511
      </CardContent>
512
    </Card>
513
  );
514
}
515
```