MantineTheme interface overview
MantineTheme is an object containing all design tokens for a Mantine application including colors, fonts, spacing, border-radius, and other design properties. The complete interface includes focusRing, scale, fontSmoothing, white, black, colors, primaryShade, primaryColor, variantColorResolver, autoContrast, luminanceThreshold, fontFamily, fontFamilyMonospace, headings, radius, defaultRadius, spacing, fontSizes, lineHeights, fontWeights, breakpoints, shadows, respectReducedMotion, cursorType, defaultGradient, activeClassName, focusClassName, components, and other properties.
focusRing property values and behavior
The focusRing property controls focus ring styles with three options: 'auto' (default, focus ring displayed only with keyboard navigation), 'always' (focus ring visible with both keyboard and mouse), and 'never' (focus ring always hidden, not recommended).
scale property for rem units
The scale property controls rem units scaling and should be changed if the font-size of the html element is customized. Default value is 1 (for 100%/16px font-size on html element).
fontSmoothing property
The fontSmoothing property determines whether the font-smoothing CSS property should be set on the body element. Default value is true.
colors property structure
The colors property is an object where each key is a color name and each value is an array of at least 10 strings representing color values (MantineThemeColors).
primaryShade property options
The primaryShade property is an index of theme.colors[color] that determines which color from the array should be used. It can be a number (0-9) or an object to specify different shades for light and dark color schemes. Default value is { light: 6, dark: 8 }.
primaryColor property
The primaryColor property is a key of theme.colors that determines which color will be used in all components by default. Hex/rgb/hsl values are not supported. Default value is 'blue'.
variantColorResolver function
The variantColorResolver property is a function that resolves colors based on variant. It can be used to deeply customize how colors are applied to Button, ActionIcon, ThemeIcon, and other components that use colors from the theme.
autoContrast property behavior
The autoContrast property determines whether text color must be changed based on the given color prop in filled variant. For example, if color='blue.1' is passed to a Button component, text color will be changed to var(--mantine-color-black). Default value is false.
luminanceThreshold property
The luminanceThreshold property determines which luminance value is used to determine if text color should be light or dark. It is used only if theme.autoContrast is set to true. Default value is 0.3.
fontFamily and fontFamilyMonospace properties
The fontFamily property sets the font-family used in all components (system fonts by default). The fontFamilyMonospace property sets the monospace font-family used in code and similar components (system fonts by default).
headings property structure
The headings property controls styles of h1-h6 elements with sub-properties: fontFamily (string), fontWeight (string), textWrap ('wrap' | 'nowrap' | 'balance' | 'pretty' | 'stable'), and sizes object containing h1-h6 HeadingStyle objects.
radius and defaultRadius properties
The radius property is an object of values used to set border-radius in all components that support it (MantineRadiusValues). The defaultRadius property is a key of theme.radius or any valid CSS value and sets the default border-radius used by most components.
spacing, fontSizes, lineHeights, and fontWeights properties
spacing is an object of values used to set various CSS properties controlling spacing between elements (MantineSpacingValues). fontSizes is an object controlling font-size property (MantineFontSizesValues). lineHeights is an object controlling line-height in Text component (MantineLineHeightValues). fontWeights is an object controlling font-weight property in components (MantineFontWeightsValues).
breakpoints and shadows properties
The breakpoints property is an object of values used to control breakpoints in all components with values expected to be defined in em (MantineBreakpointsValues). The shadows property is an object of values used to add box-shadow styles to components that support the shadow prop (MantineShadowsValues).
respectReducedMotion property
The respectReducedMotion property determines whether user OS settings to reduce motion should be respected. Default value is false.
cursorType property values
The cursorType property determines which cursor type will be used for interactive elements: 'default' (cursor used by native HTML elements, e.g., input[type='checkbox']) or 'pointer' (sets cursor: pointer on interactive elements that do not have these styles by default).
defaultGradient property
The defaultGradient property is a MantineGradient object that controls the default gradient configuration for components that support variant='gradient' (MantineGradient).
activeClassName and focusClassName properties
activeClassName is a CSS class added to elements that have active styles (e.g., Button, ActionIcon). focusClassName is a CSS class added to elements that have focus styles (e.g., Button, ActionIcon) and overrides theme.focusRing property when set.
components property
The components property (MantineThemeComponents) allows overriding of components' default props and styles with classNames and styles properties, enabling deep component customization.
other property for custom theme values
The other property (MantineThemeOther) is an object that can be used to store any other custom properties that you want to access with the theme object.
autoContrast applies to specific components
autoContrast controls text color in: ActionIcon, Alert, Avatar, Badge, Button, Chip, NavLink, ThemeIcon, Checkbox, Radio with variant='filled'; Tabs with variant='pills'; SegmentedControl, Stepper, Pagination, Progress, Indicator, Timeline, Spotlight, and all @mantine/dates components based on Calendar.
autoContrast configuration scope
autoContrast can be set globally on the theme level or individually for each component via the autoContrast prop, except for Spotlight and @mantine/dates components which only support the global theme setting.
createTheme function for theme override
To customize the theme, pass a theme override object created with createTheme to MantineProvider's theme prop. The theme override will be deeply merged with the default theme.
mergeThemeOverrides function
Use the mergeThemeOverrides function to merge multiple theme override objects into one theme override object.
useMantineTheme hook
The useMantineTheme hook returns the theme object from MantineProvider context, allowing access to theme properties within components.
DEFAULT_THEME import
The default theme object can be imported from @mantine/core as DEFAULT_THEME. It includes all theme properties with default values. When a theme override is passed to MantineProvider, it will be deeply merged with the default theme.
mergeMantineTheme function
Use mergeMantineTheme to create a full theme object by merging a theme override with the default theme. This is needed to access theme outside of components.
defaultRadius conversion from pixels to rem
Numbers in defaultRadius are treated as pixels but converted to rem. For example, theme.defaultRadius: 4 will be converted to 0.25rem.
focusRing browser support
The :focus-visible selector is supported by more than 91% of browsers (as of April 2023). Safari added support in version 15.4 (March 2022). For older Safari versions, use a focus-visible polyfill or provide a fallback with :focus pseudo-class.
Disable active styles globally
To disable active styles for all components, set theme.activeClassName to an empty string.
Create theme example with colors and shadows
Example of creating a theme with custom colors and shadows:
```tsx
import { createTheme, MantineProvider } from '@mantine/core';
const theme = createTheme({
colors: {
deepBlue: [
'#eef3ff',
'#dce4f5',
'#b9c7e2',
'#94a8d0',
'#748dc1',
'#5f7cb8',
'#5474b4',
'#44639f',
'#39588f',
'#2d4b81',
],
blue: [
'#eef3ff',
'#dee2f2',
'#bdc2de',
'#98a0ca',
'#7a84ba',
'#6672b0',
'#5c68ac',
'#4c5897',
'#424e88',
'#364379',
],
},
shadows: {
md: '1px 1px 3px rgba(0, 0, 0, .25)',
xl: '5px 5px 3px rgba(0, 0, 0, .25)',
},
headings: {
fontFamily: 'Roboto, sans-serif',
sizes: {
h1: { fontSize: '36px' },
},
},
});
function Demo() {
return (
<MantineProvider theme={theme}>
{/* Your app here */}
</MantineProvider>
);
}
```
Modify fontWeights example
Example of modifying fontWeights in a theme:
```tsx
import { createTheme, MantineProvider } from '@mantine/core';
const theme = createTheme({
fontWeights: {
medium: '500',
},
});
function Demo() {
return (
<MantineProvider theme={theme}>
{/* Your app here */}
</MantineProvider>
);
}
```
Use theme.other for custom properties example
Example of storing custom properties in theme.other:
```tsx
import { createTheme, MantineProvider } from '@mantine/core';
const theme = createTheme({
other: {
charcoal: '#333333',
primaryHeadingSize: 45,
fontWeights: {
bold: 700,
extraBold: 900,
},
},
});
function Demo() {
return (
<MantineProvider theme={theme}>
{/* Your app here */}
</MantineProvider>
);
}
```
Store theme in variable example
Example of storing a theme override object in a variable using createTheme:
```tsx
import { createTheme, MantineProvider } from '@mantine/core';
const myTheme = createTheme({
primaryColor: 'orange',
defaultRadius: 0,
});
function Demo() {
return (
<MantineProvider theme={myTheme}>
{/* Your app here */}
</MantineProvider>
);
}
```
Merge multiple theme overrides example
Example of merging multiple theme overrides:
```tsx
import {
createTheme,
MantineProvider,
mergeThemeOverrides,
} from '@mantine/core';
const theme1 = createTheme({
primaryColor: 'orange',
defaultRadius: 0,
});
const theme2 = createTheme({
cursorType: 'pointer',
});
// Note: It is better to store the theme override outside of the component body
// to prevent unnecessary re-renders
const myTheme = mergeThemeOverrides(theme1, theme2);
function Demo() {
return (
<MantineProvider theme={myTheme}>
{/* Your app here */}
</MantineProvider>
);
}
```
useMantineTheme hook example
Example of using useMantineTheme hook to access theme:
```tsx
import { useMantineTheme } from '@mantine/core';
function Demo() {
const theme = useMantineTheme();
return <div style={{ background: theme.colors.blue[5] }} />;
}
```
Access theme outside of components example
Example of accessing theme outside of components by creating a full theme object:
```tsx
// theme.ts
import {
createTheme,
DEFAULT_THEME,
mergeMantineTheme,
} from '@mantine/core';
const themeOverride = createTheme({
primaryColor: 'orange',
defaultRadius: 0,
});
export const theme = mergeMantineTheme(DEFAULT_THEME, themeOverride);
```
Then import it anywhere in the application:
```tsx
import { theme } from './theme';
```
Default fontWeights values
The default fontWeights values are: regular: 400, medium: 600, bold: 700. Each value is mapped to a CSS variable: --mantine-font-weight-regular, --mantine-font-weight-medium, --mantine-font-weight-bold.