0
# Theme System
1

2
Comprehensive theming and styling system providing complete control over component appearance, color schemes, design tokens, and global styles.
3

4
## Capabilities
5

6
### MantineProvider
7

8
The root provider component that manages theme configuration, color schemes, CSS variables, and styling context for the entire application.
9

10
```typescript { .api }
11
/**
12
 * Root provider component for Mantine theme and configuration
13
 * Must wrap your entire application to provide theme context
14
 */
15
function MantineProvider(props: MantineProviderProps): JSX.Element;
16

17
interface MantineProviderProps {
18
  /** Theme override object */
19
  theme?: MantineThemeOverride;
20
  /** Used to retrieve/set color scheme value in external storage, by default uses `window.localStorage` */
21
  colorSchemeManager?: MantineColorSchemeManager;
22
  /** Default color scheme value used when `colorSchemeManager` cannot retrieve value from external storage, `light` by default */
23
  defaultColorScheme?: MantineColorScheme;
24
  /** Forces color scheme value, if set, MantineProvider ignores `colorSchemeManager` and `defaultColorScheme` */
25
  forceColorScheme?: 'light' | 'dark';
26
  /** CSS selector to which CSS variables should be added, `:root` by default */
27
  cssVariablesSelector?: string;
28
  /** Determines whether theme CSS variables should be added to given `cssVariablesSelector` */
29
  withCssVariables?: boolean;
30
  /** Determines whether CSS variables should be deduplicated */
31
  deduplicateCssVariables?: boolean;
32
  /** Function to resolve root element to set `data-mantine-color-scheme` attribute */
33
  getRootElement?: () => HTMLElement | undefined;
34
  /** A prefix for components static classes (for example {selector}-Text-root), `mantine` by default */
35
  classNamesPrefix?: string;
36
  /** Function to generate nonce attribute added to all generated `<style />` tags */
37
  getStyleNonce?: () => string;
38
  /** Function to generate CSS variables based on theme object */
39
  cssVariablesResolver?: CSSVariablesResolver;
40
  /** Determines whether components should have static classes */
41
  withStaticClasses?: boolean;
42
  /** Determines whether global styles should be applied */
43
  withGlobalClasses?: boolean;
44
  /** Determines whether CSS reset should be applied */
45
  withCSSVariables?: boolean;
46
  /** Function to transform styles object */
47
  stylesTransform?: MantineStylesTransform;
48
  children: React.ReactNode;
49
}
50
```
51

52
**Basic Usage:**
53

54
```typescript
55
import { MantineProvider } from "@mantine/core";
56
import "@mantine/core/styles.css";
57

58
function App() {
59
  return (
60
    <MantineProvider>
61
      <YourApp />
62
    </MantineProvider>
63
  );
64
}
65
```
66

67
**With Custom Theme:**
68

69
```typescript
70
import { MantineProvider, createTheme } from "@mantine/core";
71

72
const theme = createTheme({
73
  primaryColor: 'blue',
74
  fontFamily: 'Inter, sans-serif',
75
  headings: { fontFamily: 'Inter, sans-serif' }
76
});
77

78
function App() {
79
  return (
80
    <MantineProvider theme={theme}>
81
      <YourApp />
82
    </MantineProvider>
83
  );
84
}
85
```
86

87
### HeadlessMantineProvider
88

89
Lightweight provider that provides theme context without applying CSS variables or global styles.
90

91
```typescript { .api }
92
/**
93
 * Headless provider that provides theme context without CSS variables
94
 * Useful for testing or when you want to manage styles manually
95
 */
96
function HeadlessMantineProvider(props: HeadlessMantineProviderProps): JSX.Element;
97

98
interface HeadlessMantineProviderProps {
99
  theme?: MantineThemeOverride;
100
  children: React.ReactNode;
101
}
102
```
103

104
### Theme Creation
105

106
Function to create theme configuration objects with type safety and defaults.
107

108
```typescript { .api }
109
/**
110
 * Creates a theme configuration object with proper typing
111
 * @param theme - Theme override configuration
112
 * @returns Validated theme configuration
113
 */
114
function createTheme(theme: MantineThemeOverride): MantineThemeOverride;
115

116
interface MantineTheme {
117
  /** Controls focus ring styles: 'auto' | 'always' | 'never' */
118
  focusRing: 'auto' | 'always' | 'never';
119
  /** Rem units scale, change if you customize font-size of <html /> element */
120
  scale: number;
121
  /** Determines whether font-smoothing property should be set on the body */
122
  fontSmoothing: boolean;
123
  /** White color */
124
  white: string;
125
  /** Black color */
126
  black: string;
127
  /** Object of colors, key is color name, value is an array of at least 10 strings */
128
  colors: MantineThemeColors;
129
  /** Index of theme.colors[color] used as primary shade */
130
  primaryShade: MantineColorShade | MantinePrimaryShade;
131
  /** Key of theme.colors, determines which color will be used in all components by default */
132
  primaryColor: string;
133
  /** Function to resolve colors based on variant */
134
  variantColorResolver: VariantColorsResolver;
135
  /** Determines whether text color must be changed based on the given color prop */
136
  autoContrast: boolean;
137
  /** Luminance threshold used to determine if text color should be light or dark */
138
  luminanceThreshold: number;
139
  /** Font-family used in all components */
140
  fontFamily: string;
141
  /** Monospace font-family, used in code and similar components */
142
  fontFamilyMonospace: string;
143
  /** Controls various styles of h1-h6 elements */
144
  headings: MantineHeadingsConfiguration;
145
  /** Object of values used to set border-radius in all components */
146
  radius: MantineRadiusValues;
147
  /** Default border-radius used by most components */
148
  defaultRadius: MantineRadius;
149
  /** Object of values used to control spacing between elements */
150
  spacing: MantineSpacingValues;
151
  /** Object of values used to control font-size property */
152
  fontSizes: MantineFontSizesValues;
153
  /** Object of values used to control line-height property */
154
  lineHeights: MantineLineHeightValues;
155
  /** Object of values used to control breakpoints */
156
  breakpoints: MantineBreakpointsValues;
157
  /** Object of values used to control box-shadow property */
158
  shadows: MantineShadowsValues;
159
  /** Default gradient configuration */
160
  defaultGradient: MantineGradient;
161
  /** Other CSS properties used by components */
162
  other: MantineThemeOther;
163
  /** Components theme overrides */
164
  components: MantineThemeComponents;
165
}
166

167
type MantineThemeOverride = PartialDeep<MantineTheme>;
168
```
169

170
**Advanced Theme Example:**
171

172
```typescript
173
const theme = createTheme({
174
  colors: {
175
    brand: [
176
      '#f0f9ff',
177
      '#e0f2fe',
178
      '#bae6fd',
179
      '#7dd3fc',
180
      '#38bdf8',
181
      '#0ea5e9',
182
      '#0284c7',
183
      '#0369a1',
184
      '#075985',
185
      '#0c4a6e'
186
    ],
187
    dark: [
188
      '#d5d7e0',
189
      '#acaebf',
190
      '#8c8fa3',
191
      '#666980',
192
      '#4d4f66',
193
      '#34354a',
194
      '#2b2c3d',
195
      '#1d1e30',
196
      '#0c0d21',
197
      '#01010a'
198
    ]
199
  },
200
  primaryColor: 'brand',
201
  primaryShade: { light: 6, dark: 8 },
202
  fontFamily: 'Inter, -apple-system, BlinkMacSystemFont, sans-serif',
203
  fontFamilyMonospace: 'JetBrains Mono, Consolas, Monaco, monospace',
204
  headings: {
205
    fontFamily: 'Inter, -apple-system, BlinkMacSystemFont, sans-serif',
206
    sizes: {
207
      h1: { fontSize: '2.125rem', lineHeight: '1.3', fontWeight: '700' },
208
      h2: { fontSize: '1.625rem', lineHeight: '1.35', fontWeight: '700' },
209
      h3: { fontSize: '1.375rem', lineHeight: '1.4', fontWeight: '600' },
210
      h4: { fontSize: '1.125rem', lineHeight: '1.45', fontWeight: '600' },
211
      h5: { fontSize: '1rem', lineHeight: '1.5', fontWeight: '600' },
212
      h6: { fontSize: '0.875rem', lineHeight: '1.5', fontWeight: '600' }
213
    }
214
  },
215
  defaultRadius: 'md',
216
  autoContrast: true
217
});
218
```
219

220
### Color Scheme Management
221

222
Hooks and utilities for managing light/dark color schemes with persistence and transitions.
223

224
```typescript { .api }
225
/**
226
 * Hook to manage color scheme state with transitions
227
 * @param options - Configuration options
228
 * @returns Color scheme management functions
229
 */
230
function useMantineColorScheme(options?: {
231
  keepTransitions?: boolean;
232
}): {
233
  colorScheme: MantineColorScheme;
234
  setColorScheme: (value: MantineColorScheme) => void;
235
  clearColorScheme: () => void;
236
  toggleColorScheme: (value?: MantineColorScheme) => void;
237
};
238

239
type MantineColorScheme = 'light' | 'dark' | 'auto';
240

241
/**
242
 * Color scheme manager interface for external storage
243
 */
244
interface MantineColorSchemeManager {
245
  /** Get color scheme value from external storage */
246
  get: (defaultValue: MantineColorScheme) => MantineColorScheme;
247
  /** Set color scheme value to external storage */
248
  set: (value: MantineColorScheme) => void;
249
  /** Clear color scheme value from external storage */
250
  clear: () => void;
251
}
252

253
/** Built-in localStorage color scheme manager */
254
const localStorageColorSchemeManager: MantineColorSchemeManager;
255

256
/** Built-in sessionStorage color scheme manager */  
257
const sessionStorageColorSchemeManager: MantineColorSchemeManager;
258
```
259

260
**Usage Examples:**
261

262
```typescript
263
import { useMantineColorScheme } from "@mantine/core";
264

265
function ThemeToggle() {
266
  const { colorScheme, toggleColorScheme } = useMantineColorScheme();
267
  
268
  return (
269
    <Button onClick={() => toggleColorScheme()}>
270
      {colorScheme === 'dark' ? 'Light' : 'Dark'} theme
271
    </Button>
272
  );
273
}
274

275
// Custom color scheme manager
276
const customColorSchemeManager: MantineColorSchemeManager = {
277
  get: (defaultValue) => {
278
    // Get from your custom storage
279
    return window.myStorage.getItem('color-scheme') || defaultValue;
280
  },
281
  set: (value) => {
282
    // Save to your custom storage
283
    window.myStorage.setItem('color-scheme', value);
284
  },
285
  clear: () => {
286
    window.myStorage.removeItem('color-scheme');
287
  }
288
};
289
```
290

291
### ColorSchemeScript
292

293
Script component for preventing flash of wrong theme on page load.
294

295
```typescript { .api }
296
/**
297
 * Script that should be added to prevent color scheme flash on page load
298
 * Must be added before your app renders
299
 */
300
function ColorSchemeScript(props?: {
301
  defaultColorScheme?: MantineColorScheme;
302
  localStorageKey?: string;
303
  nonce?: string;
304
}): JSX.Element;
305
```
306

307
**Usage in Next.js:**
308

309
```typescript
310
import { ColorSchemeScript } from "@mantine/core";
311

312
export default function RootLayout({
313
  children,
314
}: {
315
  children: React.ReactNode;
316
}) {
317
  return (
318
    <html lang="en">
319
      <head>
320
        <ColorSchemeScript defaultColorScheme="auto" />
321
      </head>
322
      <body>{children}</body>
323
    </html>
324
  );
325
}
326
```
327

328
### Theme Context and Hooks
329

330
Hooks for accessing theme configuration and context within components.
331

332
```typescript { .api }
333
/**
334
 * Hook to access the current theme object
335
 * @returns Current MantineTheme object
336
 */
337
function useMantineTheme(): MantineTheme;
338

339
/**
340
 * Safe version that returns default theme if provider is not found
341
 * @returns MantineTheme object or default theme
342
 */
343
function useSafeMantineTheme(): MantineTheme;
344

345
/**
346
 * Hook to access Mantine context
347
 * @returns MantineContext value
348
 */
349
function useMantineContext(): MantineContextType;
350

351
/**
352
 * Hook to get class names prefix
353
 * @returns Current class names prefix
354
 */
355
function useMantineClassNamesPrefix(): string;
356
```
357

358
### Styles API
359

360
System for applying custom styles and class names to component parts.
361

362
```typescript { .api }
363
/**
364
 * Hook to resolve and apply styles API
365
 * @param options - Styles configuration
366
 * @returns Resolved styles and class names
367
 */
368
function useStyles<StylesNames extends string = string, Vars extends Record<string, any> = Record<string, any>>(
369
  options: UseStylesOptions<StylesNames, Vars>
370
): UseStylesReturn<StylesNames>;
371

372
interface UseStylesOptions<StylesNames, Vars> {
373
  name: string | string[];
374
  classes: Record<StylesNames, string>;
375
  props: StylesApiProps<StylesNames, Vars>;
376
  stylesCtx?: Record<string, any>;
377
  rootSelector?: StylesNames;
378
  unstyled?: boolean;
379
  transformedStyles?: Record<string, React.CSSProperties>;
380
  classNames?: ClassNames<StylesNames>;
381
  styles?: Styles<StylesNames>;
382
  variant?: string;
383
  vars?: Vars;
384
  varsResolver?: VarsResolver<Vars>;
385
}
386

387
/**
388
 * Function to create CSS variables resolver
389
 * @param resolver - Resolver function
390
 * @returns VarsResolver function
391
 */
392
function createVarsResolver<Vars extends Record<string, any>>(
393
  resolver: (theme: MantineTheme, props: Vars, ctx: StylesApiContext) => CSSVariables
394
): VarsResolver<Vars>;
395
```
396

397
**Usage Examples:**
398

399
```typescript
400
// Component with Styles API
401
function CustomButton({ className, style, classNames, styles, ...others }) {
402
  const { classes, cx } = useStyles({
403
    name: 'Button',
404
    classes: buttonClasses,
405
    props: { classNames, styles },
406
    className,
407
    style,
408
  });
409

410
  return <button className={cx(classes.root, className)} {...others} />;
411
}
412

413
// Custom styles and class names
414
<Button
415
  classNames={{
416
    root: 'my-button-root',
417
    label: 'my-button-label'
418
  }}
419
  styles={{
420
    root: { borderRadius: 20 },
421
    label: { fontSize: 16 }
422
  }}
423
>
424
  Styled Button
425
</Button>
426
```
427

428
### CSS Variables System
429

430
Dynamic CSS variables generation and management system.
431

432
```typescript { .api }
433
/**
434
 * CSS variables resolver type
435
 */
436
type CSSVariablesResolver = (theme: MantineTheme) => CSSVariables;
437

438
/**
439
 * Default CSS variables resolver
440
 */
441
const defaultCssVariablesResolver: CSSVariablesResolver;
442

443
/**
444
 * Function to convert CSS variables input
445
 * @param input - CSS variables configuration
446
 * @returns Converted CSS variables
447
 */
448
function convertCssVariables(input: ConvertCSSVariablesInput): CSSVariables;
449

450
interface ConvertCSSVariablesInput {
451
  variables?: Record<string, string>;
452
  dark?: Record<string, string>;
453
  light?: Record<string, string>;
454
}
455

456
/**
457
 * Virtual color utilities for CSS variables
458
 */
459
function virtualColor(color: string): string;
460
function isVirtualColor(color: string): boolean;
461
function getCSSColorVariables(colors: Record<string, string[]>): CSSVariables;
462
```
463

464
### Direction Provider
465

466
Provider for RTL/LTR text direction support.
467

468
```typescript { .api }
469
/**
470
 * Provider for RTL/LTR text direction support
471
 * @param props - Direction provider props
472
 */
473
function DirectionProvider(props: DirectionProviderProps): JSX.Element;
474

475
interface DirectionProviderProps {
476
  /** Text direction, 'ltr' by default */
477
  dir?: 'ltr' | 'rtl';
478
  /** Determines whether direction should be set on document.documentElement, true by default */
479
  detectDirection?: boolean;
480
  children: React.ReactNode;
481
}
482

483
/**
484
 * Hook to get current text direction
485
 * @returns Current direction ('ltr' | 'rtl')
486
 */
487
function useDirection(): { dir: 'ltr' | 'rtl' };
488
```
489

490
### Theme Utilities
491

492
Utility functions for theme manipulation and merging.
493

494
```typescript { .api }
495
/**
496
 * Validates Mantine theme object
497
 * @param theme - Theme to validate
498
 * @returns Validated theme
499
 */
500
function validateMantineTheme(theme: MantineThemeOverride): MantineTheme;
501

502
/**
503
 * Merges theme with base theme
504
 * @param currentTheme - Current theme
505
 * @param themeOverride - Theme override
506
 * @returns Merged theme
507
 */
508
function mergeMantineTheme(currentTheme: MantineTheme, themeOverride: MantineThemeOverride): MantineTheme;
509

510
/**
511
 * Merges theme overrides
512
 * @param currentTheme - Current theme override
513
 * @param otherTheme - Other theme override
514
 * @returns Merged theme override
515
 */
516
function mergeThemeOverrides(currentTheme: MantineThemeOverride, otherTheme: MantineThemeOverride): MantineThemeOverride;
517
```