0
# Theming and Styling
1

2
Material-UI's theming system provides centralized configuration for colors, typography, spacing, and styling throughout your application. It includes CSS-in-JS styling utilities built on JSS.
3

4
## Capabilities
5

6
### Theme Creation
7

8
Creates a Material-UI theme with custom configuration options.
9

10
```typescript { .api }
11
/**
12
 * Creates a Material-UI theme with custom configuration options
13
 * @param options - Theme configuration options
14
 * @returns Configured theme object
15
 */
16
function createMuiTheme(options?: ThemeOptions): Theme;
17

18
interface ThemeOptions {
19
  breakpoints?: BreakpointsOptions;
20
  direction?: Direction;
21
  mixins?: MixinsOptions;
22
  overrides?: Overrides;
23
  palette?: PaletteOptions;
24
  props?: ComponentsProps;
25
  shadows?: Shadows;
26
  spacing?: SpacingOptions;
27
  transitions?: TransitionsOptions;
28
  typography?: TypographyOptions;
29
  zIndex?: ZIndexOptions;
30
  shape?: ShapeOptions;
31
}
32

33
interface Theme {
34
  palette: Palette;
35
  typography: Typography;
36
  spacing: Spacing;
37
  breakpoints: Breakpoints;
38
  shadows: Shadows;
39
  transitions: Transitions;
40
  zIndex: ZIndex;
41
  shape: Shape;
42
  mixins: Mixins;
43
  direction: Direction;
44
  overrides?: Overrides;
45
  props?: ComponentsProps;
46
}
47
```
48

49
**Usage Examples:**
50

51
```typescript
52
import { createMuiTheme } from '@material-ui/core/styles';
53
import { blue, red } from '@material-ui/core/colors';
54

55
// Basic theme with custom colors
56
const theme = createMuiTheme({
57
  palette: {
58
    primary: blue,
59
    secondary: red,
60
    type: 'dark',
61
  },
62
});
63

64
// Advanced theme configuration
65
const advancedTheme = createMuiTheme({
66
  palette: {
67
    primary: {
68
      main: '#1976d2',
69
    },
70
    secondary: {
71
      main: '#dc004e',
72
    },
73
  },
74
  typography: {
75
    fontFamily: '"Roboto", "Helvetica", "Arial", sans-serif',
76
    h1: {
77
      fontSize: '2.5rem',
78
      fontWeight: 300,
79
    },
80
  },
81
  spacing: 8,
82
  shape: {
83
    borderRadius: 4,
84
  },
85
});
86
```
87

88
### Theme Provider
89

90
Provides theme context to the component tree.
91

92
```typescript { .api }
93
/**
94
 * Provides theme context to the component tree
95
 * @param props - Theme provider props
96
 * @returns React component providing theme context
97
 */
98
function ThemeProvider(props: ThemeProviderProps): JSX.Element;
99

100
interface ThemeProviderProps {
101
  children: React.ReactNode;
102
  theme: Theme | ((outerTheme: Theme) => Theme);
103
}
104
```
105

106
```typescript
107
import { ThemeProvider } from '@material-ui/core/styles';
108

109
function App() {
110
  return (
111
    <ThemeProvider theme={theme}>
112
      <YourApplication />
113
    </ThemeProvider>
114
  );
115
}
116
```
117

118
### Component Styling
119

120
Higher-order component for styling components with theme integration.
121

122
```typescript { .api }
123
/**
124
 * Higher-order component for styling components with theme integration
125
 * @param styles - Styles object or function returning styles
126
 * @param options - Styling options
127
 * @returns HOC that provides classes prop to wrapped component
128
 */
129
function withStyles<P extends object>(
130
  styles: Styles<Theme, P>,
131
  options?: WithStylesOptions<Theme>
132
): (Component: React.ComponentType<P>) => React.ComponentType<P>;
133

134
type Styles<Theme, Props extends object> = 
135
  | Record<string, CSSProperties | CreateCSSProperties<Props> | PropsFunc<Props, CreateCSSProperties<Props>>>
136
  | ((theme: Theme) => Record<string, CSSProperties | CreateCSSProperties<Props> | PropsFunc<Props, CreateCSSProperties<Props>>>);
137

138
interface WithStylesOptions<Theme = DefaultTheme> extends JSS.StyleSheetFactoryOptions {
139
  defaultTheme?: Theme;
140
  withTheme?: boolean;
141
  name?: string;
142
  flip?: boolean;
143
  index?: number;
144
}
145
```
146

147
**Usage Examples:**
148

149
```typescript
150
import { withStyles } from '@material-ui/core/styles';
151

152
const styles = (theme) => ({
153
  root: {
154
    padding: theme.spacing(2),
155
    backgroundColor: theme.palette.background.paper,
156
    borderRadius: theme.shape.borderRadius,
157
  },
158
  title: {
159
    color: theme.palette.primary.main,
160
    marginBottom: theme.spacing(1),
161
  },
162
});
163

164
const StyledComponent = withStyles(styles)(({ classes, title, children }) => (
165
  <div className={classes.root}>
166
    <h2 className={classes.title}>{title}</h2>
167
    {children}
168
  </div>
169
));
170
```
171

172
### Theme Access
173

174
Higher-order component for accessing theme in components.
175

176
```typescript { .api }
177
/**
178
 * Higher-order component for accessing theme in components
179
 * @param Component - Component to wrap with theme access
180
 * @returns Component with theme prop injected
181
 */
182
function withTheme<P extends WithThemeProps<Theme>>(
183
  Component: React.ComponentType<P>
184
): React.ComponentType<Omit<P, keyof WithThemeProps<Theme>>>;
185

186
interface WithThemeProps<Theme> {
187
  theme: Theme;
188
}
189
```
190

191
### Style Creation
192

193
Creates typed styles object for TypeScript integration.
194

195
```typescript { .api }
196
/**
197
 * Creates typed styles object for TypeScript integration
198
 * @param styles - Styles object
199
 * @returns Typed styles object
200
 */
201
function createStyles<T extends Record<string, CSSProperties | CreateCSSProperties>>(styles: T): T;
202
```
203

204
### Class Name Generation
205

206
Creates class name generator with custom configuration.
207

208
```typescript { .api }
209
/**
210
 * Creates class name generator with custom configuration
211
 * @param options - Class name generator options
212
 * @returns Class name generator function
213
 */
214
function createGenerateClassName(options?: CreateGenerateClassNameOptions): GenerateClassName;
215

216
interface CreateGenerateClassNameOptions {
217
  dangerouslyUseGlobalCSS?: boolean;
218
  productionPrefix?: string;
219
  seed?: string;
220
}
221

222
type GenerateClassName = (rule: object, sheet?: object) => string;
223
```
224

225
### JSS Preset
226

227
JSS preset with Material-UI specific plugins and configuration.
228

229
```typescript { .api }
230
/**
231
 * JSS preset with Material-UI specific plugins and configuration
232
 * @returns JSS preset object
233
 */
234
function jssPreset(): JSS.Preset;
235
```
236

237
## Theme Structure
238

239
### Palette
240

241
```typescript { .api }
242
interface Palette {
243
  type: PaletteType;
244
  common: CommonColors;
245
  primary: PaletteColor;
246
  secondary: PaletteColor;
247
  error: PaletteColor;
248
  grey: Color;
249
  contrastThreshold: number;
250
  tonalOffset: number;
251
  text: TypeText;
252
  divider: string;
253
  action: TypeAction;
254
  background: TypeBackground;
255
}
256

257
interface PaletteColor {
258
  light: string;
259
  main: string;
260
  dark: string;
261
  contrastText: string;
262
}
263
```
264

265
### Typography
266

267
```typescript { .api }
268
interface Typography extends Record<TypographyVariant, TypographyStyle> {
269
  pxToRem: (px: number) => string;
270
  round: (px: number) => number;
271
  fontFamily: string;
272
  fontSize: number;
273
  fontWeightLight: number;
274
  fontWeightRegular: number;
275
  fontWeightMedium: number;
276
  fontWeightBold: number;
277
}
278

279
interface TypographyStyle {
280
  fontFamily: string;
281
  fontWeight: number;
282
  fontSize: string;
283
  lineHeight: number;
284
  letterSpacing?: string;
285
  color?: string;
286
  textTransform?: string;
287
}
288
```
289

290
### Spacing
291

292
```typescript { .api }
293
type Spacing = (factor: number) => number;
294
```
295

296
### Breakpoints
297

298
```typescript { .api }
299
interface Breakpoints {
300
  keys: Breakpoint[];
301
  values: Record<Breakpoint, number>;
302
  up: (key: Breakpoint | number) => string;
303
  down: (key: Breakpoint | number) => string;
304
  between: (start: Breakpoint | number, end: Breakpoint | number) => string;
305
  only: (key: Breakpoint) => string;
306
  width: (key: Breakpoint) => number;
307
}
308
```
309

310
### Transitions
311

312
```typescript { .api }
313
interface Transitions {
314
  easing: {
315
    easeInOut: string;
316
    easeOut: string;
317
    easeIn: string;
318
    sharp: string;
319
  };
320
  duration: {
321
    shortest: number;
322
    shorter: number;
323
    short: number;
324
    standard: number;
325
    complex: number;
326
    enteringScreen: number;
327
    leavingScreen: number;
328
  };
329
  create: (
330
    props: string | string[],
331
    options?: Partial<{
332
      duration: number | string;
333
      easing: string;
334
      delay: number | string;
335
    }>
336
  ) => string;
337
}
338
```
339

340
### Shadows
341

342
```typescript { .api }
343
type Shadows = [
344
  'none',
345
  string,
346
  string,
347
  string,
348
  string,
349
  string,
350
  string,
351
  string,
352
  string,
353
  string,
354
  string,
355
  string,
356
  string,
357
  string,
358
  string,
359
  string,
360
  string,
361
  string,
362
  string,
363
  string,
364
  string,
365
  string,
366
  string,
367
  string,
368
  string
369
];
370
```
371

372
### Z-Index
373

374
```typescript { .api }
375
interface ZIndex {
376
  mobileStepper: number;
377
  appBar: number;
378
  drawer: number;
379
  modal: number;
380
  snackbar: number;
381
  tooltip: number;
382
}
383
```