0
# Theme System
1

2
Complete theming system for creating consistent design tokens, providing theme context, and accessing theme values in components. The theme system enables centralized design management and consistent styling across applications.
3

4
## Capabilities
5

6
### Theme Creation
7

8
Creates complete theme objects with default values and custom configuration options.
9

10
```typescript { .api }
11
/**
12
 * Generate a theme based on the options received
13
 * @param options - Takes an incomplete theme object and adds the missing parts
14
 * @param args - Deep merge the arguments with the about to be returned theme
15
 * @returns A complete, ready-to-use theme object
16
 */
17
function createTheme(options?: ThemeOptions, ...args: object[]): Theme;
18

19
interface ThemeOptions {
20
  /** Shape configuration for border radius */
21
  shape?: ShapeOptions;
22
  
23
  /** Breakpoint system configuration */
24
  breakpoints?: BreakpointsOptions;
25
  
26
  /** Text direction (left-to-right or right-to-left) */
27
  direction?: Direction;
28
  
29
  /** Component mixins and utilities */
30
  mixins?: Mixins;
31
  
32
  /** Color palette configuration */
33
  palette?: Record<string, any>;
34
  
35
  /** Shadow elevation system */
36
  shadows?: Shadows;
37
  
38
  /** Spacing function configuration */
39
  spacing?: SpacingOptions;
40
  
41
  /** Animation and transition configuration */
42
  transitions?: Transitions;
43
  
44
  /** Component default props and style overrides */
45
  components?: Record<string, any>;
46
  
47
  /** Typography system configuration */
48
  typography?: Typography;
49
  
50
  /** Z-index layering system */
51
  zIndex?: ZIndex;
52
  
53
  /** sx prop configuration (advanced) */
54
  unstable_sxConfig?: SxConfig;
55
}
56

57
interface Theme extends CssContainerQueries {
58
  /** Shape configuration (border radius) */
59
  shape: Shape;
60
  
61
  /** Breakpoint system with helper methods */
62
  breakpoints: Breakpoints;
63
  
64
  /** Text direction */
65
  direction: Direction;
66
  
67
  /** Color palette with mode support */
68
  palette: Record<string, any> & { mode: 'light' | 'dark' };
69
  
70
  /** Shadow elevation values */
71
  shadows?: Shadows;
72
  
73
  /** Spacing transformation function */
74
  spacing: Spacing;
75
  
76
  /** Animation and transition configuration */
77
  transitions?: Transitions;
78
  
79
  /** Component default props and overrides */
80
  components?: Record<string, any>;
81
  
82
  /** Component mixins and utilities */
83
  mixins?: Mixins;
84
  
85
  /** Typography system */
86
  typography?: Typography;
87
  
88
  /** Z-index layering values */
89
  zIndex?: ZIndex;
90
  
91
  /** Apply styles conditionally based on color scheme */
92
  applyStyles: ApplyStyles<'light' | 'dark'>;
93
  
94
  /** sx prop configuration */
95
  unstable_sxConfig: SxConfig;
96
  
97
  /** sx prop processor function */
98
  unstable_sx: (props: SxProps<Theme>) => CSSObject;
99
}
100

101
type Direction = 'ltr' | 'rtl';
102

103
// Empty interfaces for module augmentation
104
interface Typography {}
105
interface Mixins {}
106
interface Shadows {}
107
interface Transitions {}
108
interface ZIndex {}
109
```
110

111
**Usage Examples:**
112

113
```typescript
114
import { createTheme } from "@mui/system";
115

116
// Basic theme
117
const theme = createTheme();
118

119
// Custom theme with palette
120
const customTheme = createTheme({
121
  palette: {
122
    primary: {
123
      main: '#1976d2',
124
      light: '#42a5f5',
125
      dark: '#1565c0',
126
    },
127
    secondary: {
128
      main: '#dc004e',
129
    },
130
    mode: 'light',
131
  },
132
  spacing: 8,
133
  shape: {
134
    borderRadius: 4,
135
  },
136
});
137

138
// Dark theme
139
const darkTheme = createTheme({
140
  palette: {
141
    mode: 'dark',
142
    primary: {
143
      main: '#90caf9',
144
    },
145
    background: {
146
      default: '#121212',
147
      paper: '#1e1e1e',
148
    },
149
  },
150
});
151

152
// Theme with breakpoints
153
const responsiveTheme = createTheme({
154
  breakpoints: {
155
    values: {
156
      xs: 0,
157
      sm: 600,
158
      md: 900,
159
      lg: 1200,
160
      xl: 1536,
161
    },
162
  },
163
});
164
```
165

166
### Theme Provider
167

168
Provides theme context to child components through React Context API.
169

170
```typescript { .api }
171
/**
172
 * Theme context provider component
173
 * @param props - ThemeProvider props
174
 * @returns Provider component
175
 */
176
declare const ThemeProvider: React.ComponentType<ThemeProviderProps>;
177

178
interface ThemeProviderProps<Theme = Theme> {
179
  /** Child components that will receive theme context */
180
  children: React.ReactNode;
181
  
182
  /** Theme object to provide */
183
  theme: Theme | ((outerTheme: Theme) => Theme);
184
  
185
  /** Optional theme identifier for multiple theme contexts */
186
  themeId?: string;
187
}
188
```
189

190
**Usage Examples:**
191

192
```typescript
193
import { ThemeProvider, createTheme } from "@mui/system";
194

195
const theme = createTheme({
196
  palette: {
197
    primary: { main: '#1976d2' },
198
  },
199
});
200

201
function App() {
202
  return (
203
    <ThemeProvider theme={theme}>
204
      <div>
205
        {/* All child components have access to theme */}
206
        <MyComponent />
207
      </div>
208
    </ThemeProvider>
209
  );
210
}
211

212
// Function theme (access to outer theme)
213
<ThemeProvider theme={(outerTheme) => ({
214
  ...outerTheme,
215
  palette: {
216
    ...outerTheme.palette,
217
    primary: { main: '#ff5722' },
218
  },
219
})}>
220
  <MyComponent />
221
</ThemeProvider>
222
```
223

224
### Theme Hooks
225

226
React hooks for accessing and using theme values in components.
227

228
```typescript { .api }
229
/**
230
 * Hook to access the current theme
231
 * @param defaultTheme - Default theme if no theme provider exists
232
 * @returns Current theme object
233
 */
234
function useTheme<T = Theme>(defaultTheme?: T): T;
235

236
/**
237
 * Hook to access theme without default fallback
238
 * @returns Current theme object or undefined
239
 */
240
function useThemeWithoutDefault<T = Theme>(): T | undefined;
241

242
/**
243
 * Hook to merge component props with theme defaults
244
 * @param params - Props merging parameters
245
 * @returns Merged props with theme defaults
246
 */
247
function useThemeProps<Theme, Props, Name extends string>(params: {
248
  props: Props;
249
  name: Name;
250
  defaultTheme?: Theme;
251
  themeId?: string;
252
}): Props & ThemedProps<Theme, Name>;
253

254
/**
255
 * Utility function to get theme props (non-hook version)
256
 * @param params - Props merging parameters
257
 * @returns Merged props with theme defaults
258
 */
259
function getThemeProps<Theme, Props, Name extends string>(params: {
260
  props: Props;
261
  name: Name;
262
  theme: Theme;
263
}): Props & ThemedProps<Theme, Name>;
264

265
type ThemedProps<Theme, Name extends string> = {
266
  [K in keyof Theme]: Theme[K];
267
};
268
```
269

270
**Usage Examples:**
271

272
```typescript
273
import { useTheme, useThemeProps } from "@mui/system";
274

275
// Access theme in component
276
function MyComponent() {
277
  const theme = useTheme();
278
  
279
  return (
280
    <div style={{
281
      backgroundColor: theme.palette.primary.main,
282
      padding: theme.spacing(2),
283
      borderRadius: theme.shape.borderRadius,
284
    }}>
285
      Themed component
286
    </div>
287
  );
288
}
289

290
// Custom hook with theme
291
function useCustomStyles() {
292
  const theme = useTheme();
293
  
294
  return {
295
    container: {
296
      padding: theme.spacing(2),
297
      [theme.breakpoints.up('md')]: {
298
        padding: theme.spacing(3),
299
      },
300
    },
301
  };
302
}
303

304
// Component with theme props
305
function ThemedButton(inProps) {
306
  const props = useThemeProps({
307
    props: inProps,
308
    name: 'MyButton',
309
  });
310
  
311
  const { children, ...other } = props;
312
  
313
  return <button {...other}>{children}</button>;
314
}
315
```
316

317
### Breakpoints System
318

319
Responsive breakpoint system with helper methods for media queries and responsive values.
320

321
```typescript { .api }
322
/**
323
 * Create breakpoints system with helper methods
324
 * @param options - Breakpoint configuration options
325
 * @returns Breakpoints object with helper methods
326
 */
327
function createBreakpoints(options?: BreakpointsOptions): Breakpoints;
328

329
interface BreakpointsOptions {
330
  /** Breakpoint values in pixels */
331
  values?: BreakpointValues;
332
  
333
  /** CSS unit for breakpoints (default: 'px') */
334
  unit?: string;
335
  
336
  /** Step increment for between() method (default: 5) */
337
  step?: number;
338
}
339

340
interface BreakpointValues {
341
  xs: number;
342
  sm: number;
343
  md: number;
344
  lg: number;
345
  xl: number;
346
  [key: string]: number;
347
}
348

349
interface Breakpoints {
350
  /** Breakpoint keys array */
351
  keys: Breakpoint[];
352
  
353
  /** Breakpoint values object */
354
  values: BreakpointValues;
355
  
356
  /** CSS unit used for breakpoints */
357
  unit: string;
358
  
359
  /** Step increment for between() method */
360
  step: number;
361
  
362
  /** Generate min-width media query */
363
  up(key: Breakpoint | number): string;
364
  
365
  /** Generate max-width media query */
366
  down(key: Breakpoint | number): string;
367
  
368
  /** Generate media query between two breakpoints */
369
  between(start: Breakpoint | number, end: Breakpoint | number): string;
370
  
371
  /** Generate media query for specific breakpoint only */
372
  only(key: Breakpoint): string;
373
  
374
  /** Generate media query excluding specific breakpoint */
375
  not(key: Breakpoint): string;
376
}
377

378
type Breakpoint = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
379

380
// Re-exported from breakpoints module
381
export {
382
  Breakpoint,
383
  Breakpoints,
384
  BreakpointOverrides, // Module augmentation interface
385
};
386
```
387

388
**Usage Examples:**
389

390
```typescript
391
import { createBreakpoints } from "@mui/system";
392

393
// Default breakpoints
394
const breakpoints = createBreakpoints();
395

396
// Custom breakpoints
397
const customBreakpoints = createBreakpoints({
398
  values: {
399
    xs: 0,
400
    sm: 576,
401
    md: 768,
402
    lg: 992,
403
    xl: 1200,
404
    xxl: 1400,
405
  },
406
});
407

408
// Using breakpoint helpers
409
const styles = {
410
  container: {
411
    width: '100%',
412
    [breakpoints.up('sm')]: {
413
      maxWidth: '540px',
414
    },
415
    [breakpoints.up('md')]: {
416
      maxWidth: '720px',
417
    },
418
    [breakpoints.between('md', 'xl')]: {
419
      padding: '0 16px',
420
    },
421
  },
422
};
423
```
424

425
### Spacing System
426

427
Configurable spacing system for consistent spacing values throughout the application.
428

429
```typescript { .api }
430
/**
431
 * Create spacing transformation function
432
 * @param spacingInput - Spacing configuration
433
 * @returns Spacing function
434
 */
435
function createSpacing(spacingInput?: SpacingOptions): Spacing;
436

437
type SpacingOptions = 
438
  | number 
439
  | number[] 
440
  | ((factor: number) => number | string)
441
  | { unit?: string; factor?: number };
442

443
/**
444
 * Spacing transformation function
445
 * @param value - Spacing value(s) to transform
446
 * @returns CSS spacing value(s)
447
 */
448
interface Spacing {
449
  (value: number): string;
450
  (value1: number, value2: number): string;
451
  (value1: number, value2: number, value3: number): string;
452
  (value1: number, value2: number, value3: number, value4: number): string;
453
  (...values: number[]): string;
454
}
455
```
456

457
**Usage Examples:**
458

459
```typescript
460
import { createSpacing } from "@mui/system";
461

462
// Default spacing (8px base)
463
const spacing = createSpacing();
464
spacing(1); // '8px'
465
spacing(2); // '16px'
466
spacing(1, 2); // '8px 16px'
467

468
// Custom spacing unit
469
const customSpacing = createSpacing(4);
470
customSpacing(1); // '4px'
471
customSpacing(2); // '8px'
472

473
// Array-based spacing
474
const arraySpacing = createSpacing([0, 4, 8, 16, 32]);
475
arraySpacing(1); // '4px'
476
arraySpacing(4); // '32px'
477

478
// Function-based spacing
479
const funcSpacing = createSpacing((factor) => `${factor * 0.5}rem`);
480
funcSpacing(2); // '1rem'
481
```
482

483
### Shape System
484

485
Shape configuration for consistent border radius values.
486

487
```typescript { .api }
488
/**
489
 * Default shape configuration
490
 */
491
const shape: Shape;
492

493
interface Shape {
494
  /** Default border radius value */
495
  borderRadius: number;
496
}
497

498
interface ShapeOptions {
499
  /** Border radius configuration */
500
  borderRadius?: number;
501
}
502
```
503

504
**Usage Examples:**
505

506
```typescript
507
import { createTheme } from "@mui/system";
508

509
// Theme with custom shape
510
const theme = createTheme({
511
  shape: {
512
    borderRadius: 8,
513
  },
514
});
515

516
// Using shape in styles
517
const styles = {
518
  card: {
519
    borderRadius: theme.shape.borderRadius,
520
  },
521
};
522
```
523

524
### Color Scheme Support
525

526
Conditional styling based on light/dark color schemes.
527

528
```typescript { .api }
529
/**
530
 * Apply styles conditionally based on color scheme
531
 * @param colorScheme - Target color scheme
532
 * @returns Style application function
533
 */
534
type ApplyStyles<ColorScheme extends string> = (
535
  colorScheme: ColorScheme
536
) => (styles: CSSObject) => CSSObject;
537
```
538

539
**Usage Examples:**
540

541
```typescript
542
import { createTheme } from "@mui/system";
543

544
const theme = createTheme({
545
  palette: {
546
    mode: 'light',
547
  },
548
});
549

550
// Conditional styles based on color scheme
551
const styles = {
552
  paper: {
553
    backgroundColor: '#fff',
554
    ...theme.applyStyles('dark', {
555
      backgroundColor: '#1e1e1e',
556
    }),
557
  },
558
};
559
```
560

561
### Default Props Provider
562

563
Provider for setting default props for components without theme integration.
564

565
```typescript { .api }
566
/**
567
 * Provider for default component props
568
 * @param props - Provider props
569
 * @returns Provider component
570
 */
571
declare const DefaultPropsProvider: React.ComponentType<DefaultPropsProviderProps>;
572

573
interface DefaultPropsProviderProps {
574
  /** Child components */
575
  children: React.ReactNode;
576
  
577
  /** Default props configuration */
578
  value: Record<string, any> | undefined;
579
}
580

581
/**
582
 * Hook to access default props for a component
583
 * @param params - Component name and props
584
 * @returns Merged props with defaults
585
 */
586
function useDefaultProps<Props>(params: {
587
  props: Props;
588
  name: string;
589
}): Props;
590
```
591

592
**Usage Examples:**
593

594
```typescript
595
import { DefaultPropsProvider, useDefaultProps } from "@mui/system";
596

597
// Provider setup
598
const defaultProps = {
599
  Button: {
600
    variant: 'contained',
601
    color: 'primary',
602
  },
603
  TextField: {
604
    variant: 'outlined',
605
    fullWidth: true,
606
  },
607
};
608

609
function App() {
610
  return (
611
    <DefaultPropsProvider value={defaultProps}>
612
      <MyComponents />
613
    </DefaultPropsProvider>
614
  );
615
}
616

617
// Using in component
618
function MyButton(inProps) {
619
  const props = useDefaultProps({
620
    props: inProps,
621
    name: 'Button',
622
  });
623
  
624
  return <button {...props} />;
625
}
626
```
627

628
### CSS Variables System (Unstable)
629

630
Advanced CSS custom properties system for dynamic theming and runtime theme switching with color scheme support.
631

632
```typescript { .api }
633
/**
634
 * Create CSS variables provider for runtime theme switching
635
 * @param options - CSS variables provider configuration
636
 * @returns Provider component and utilities
637
 */
638
function unstable_createCssVarsProvider<
639
  ColorScheme extends string,
640
  Identifier extends string | undefined = undefined
641
>(
642
  options: CssVarsProviderConfig<ColorScheme> & {
643
    themeId?: Identifier;
644
    theme: any;
645
    resolveTheme?: (theme: any) => any;
646
  }
647
): CreateCssVarsProviderResult<ColorScheme, Identifier>;
648

649
interface CssVarsProviderConfig<ColorScheme extends string> {
650
  /** DOM attribute for applying color scheme (default: 'data-color-scheme') */
651
  attribute?: string;
652
  
653
  /** localStorage key for mode storage (default: 'mode') */
654
  modeStorageKey?: string;
655
  
656
  /** localStorage key for color scheme storage (default: 'color-scheme') */
657
  colorSchemeStorageKey?: string;
658
  
659
  /** Default color scheme configuration */
660
  defaultColorScheme: ColorScheme | { light: ColorScheme; dark: ColorScheme };
661
  
662
  /** Disable CSS transitions when switching themes */
663
  disableTransitionOnChange?: boolean;
664
  
665
  /** Force theme re-render when mode changes */
666
  forceThemeRerender?: boolean;
667
}
668

669
interface CreateCssVarsProviderResult<
670
  ColorScheme extends string,
671
  Identifier extends string | undefined
672
> {
673
  /** CSS variables provider component */
674
  CssVarsProvider: React.ComponentType<CssVarsProviderProps<ColorScheme>>;
675
  
676
  /** Hook to access color scheme state and controls */
677
  useColorScheme: () => ColorSchemeContextValue<ColorScheme>;
678
  
679
  /** Hook to get current color scheme without setters */
680
  getInitColorSchemeScript: (options?: InitColorSchemeScriptOptions) => React.ReactElement;
681
}
682

683
interface CssVarsProviderProps<ColorScheme extends string> {
684
  children: React.ReactNode;
685
  theme?: {
686
    cssVariables?: false;
687
    cssVarPrefix?: string;
688
    colorSchemes: Partial<Record<ColorScheme, any>>;
689
    colorSchemeSelector?: 'media' | 'class' | 'data' | string;
690
  };
691
  defaultMode?: 'light' | 'dark' | 'system';
692
  documentNode?: Document | null;
693
  colorSchemeNode?: Element | null;
694
  storageManager?: StorageManager | null;
695
  storageWindow?: Window | null;
696
  disableNestedContext?: boolean;
697
  disableStyleSheetGeneration?: boolean;
698
}
699

700
/**
701
 * Create CSS variable getter function
702
 * @param prefix - CSS variable prefix
703
 * @returns Function to get CSS variable reference
704
 */
705
function unstable_createGetCssVar(prefix?: string): (field: string) => string;
706

707
/**
708
 * Parse theme object into CSS variables
709
 * @param theme - Theme object to parse
710
 * @param options - Parsing options
711
 * @returns CSS variables object
712
 */
713
function unstable_cssVarsParser<Theme>(
714
  theme: Theme,
715
  options?: { prefix?: string }
716
): Record<string, string>;
717

718
/**
719
 * Prepare theme with CSS variables support
720
 * @param theme - Theme object
721
 * @param options - Preparation options
722
 * @returns Theme with CSS variables
723
 */
724
function unstable_prepareCssVars<Theme>(
725
  theme: Theme,
726
  options?: { prefix?: string }
727
): Theme & { cssVars: Record<string, string> };
728

729
/**
730
 * Create theme with CSS variables integration
731
 * @param options - Theme creation options
732
 * @returns Theme with CSS variables support
733
 */
734
function unstable_createCssVarsTheme<Theme>(options: any): Theme & {
735
  cssVars: Record<string, string>;
736
};
737

738
// Storage manager interface
739
interface StorageManager {
740
  get(key: string): string | null;
741
  set(key: string, value: string): void;
742
}
743

744
// Color scheme context value
745
interface ColorSchemeContextValue<SupportedColorScheme extends string> {
746
  mode: 'light' | 'dark' | 'system';
747
  setMode: (mode: 'light' | 'dark' | 'system') => void;
748
  colorScheme: SupportedColorScheme;
749
  setColorScheme: (colorScheme: SupportedColorScheme) => void;
750
  allColorSchemes: SupportedColorScheme[];
751
}
752
```
753

754
**Usage Examples:**
755

756
```typescript
757
import { unstable_createCssVarsProvider, createTheme } from "@mui/system";
758

759
// Create theme with color schemes
760
const theme = createTheme({
761
  colorSchemes: {
762
    light: {
763
      palette: {
764
        primary: { main: '#1976d2' },
765
        background: { default: '#ffffff' },
766
      },
767
    },
768
    dark: {
769
      palette: {
770
        primary: { main: '#90caf9' },
771
        background: { default: '#121212' },
772
      },
773
    },
774
  },
775
});
776

777
// Create CSS variables provider
778
const { CssVarsProvider, useColorScheme } = unstable_createCssVarsProvider({
779
  themeId: 'my-theme',
780
  theme,
781
  defaultColorScheme: 'light',
782
});
783

784
// App with CSS variables support
785
function App() {
786
  return (
787
    <CssVarsProvider defaultMode="system">
788
      <MyComponent />
789
    </CssVarsProvider>
790
  );
791
}
792

793
// Component using color scheme
794
function ThemeSwitcher() {
795
  const { mode, setMode, colorScheme, setColorScheme } = useColorScheme();
796
  
797
  return (
798
    <div>
799
      <button onClick={() => setMode(mode === 'dark' ? 'light' : 'dark')}>
800
        Toggle {mode} mode
801
      </button>
802
      <p>Current color scheme: {colorScheme}</p>
803
    </div>
804
  );
805
}
806

807
// Using CSS variables in styles
808
const StyledComponent = styled('div')(({ theme }) => ({
809
  backgroundColor: 'var(--mui-palette-background-default)',
810
  color: 'var(--mui-palette-primary-main)',
811
  padding: theme.spacing(2),
812
}));
813
```
814

815
## Theme Integration
816

817
The theme system integrates with all MUI System components and utilities:
818

819
- **System Props**: All style functions automatically access theme values
820
- **sx Prop**: Direct theme access with `theme => theme.palette.primary.main` syntax
821
- **Responsive Values**: Breakpoint-aware styling using theme breakpoints
822
- **Component Overrides**: Centralized component styling through theme configuration
823
- **CSS Variables**: Automatic CSS custom property generation for dynamic theming