Theme object

Mantine theme is an object where your application's colors, fonts, spacing, border-radius and other design tokens are stored.

interface MantineTheme {
// Defines color scheme for all components, defaults to "light"
colorScheme: 'light' | 'dark';
// Controls focus ring styles:
// auto – display focus ring only when user navigates with keyboard (default)
// always – display focus ring when user navigates with keyboard and mouse
// never – focus ring is always hidden (not recommended)
focusRing: 'auto' | 'always' | 'never';
// Determines whether motion based animations should be disabled for
// users who prefer to reduce motion in their OS settings
respectReducedMotion: boolean;
// Determines whether elements that do not have pointer cursor by default
// (checkboxes, radio, native select) should have it
cursorType: 'default' | 'pointer';
// Default border-radius used for most elements
defaultRadius: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | number;
// White and black colors, defaults to '#fff' and '#000'
white: string;
black: string;
// Object of arrays with 10 colors
colors: Record<string, Tuple<string, 10>>;
// Key of theme.colors
primaryColor: string;
// Index of color from theme.colors that is considered primary, Shade type is 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
primaryShade: Shade | { light: Shade; dark: Shade };
// Default gradient used in components that support `variant="gradient"` (Button, ThemeIcon, etc.)
defaultGradient: { deg: number; from: MantineColor; to: MantineColor };
// font-family and line-height used in most components
fontFamily: string;
lineHeight: string | number;
// Timing function used for animations, defaults to 'ease'
transitionTimingFunction: string;
// Monospace font-family, used in Code, Kbd and Prism components
fontFamilyMonospace: string;
// Sizes for corresponding properties
fontSizes: Record<'xs' | 'sm' | 'md' | 'lg' | 'xl', number>;
radius: Record<'xs' | 'sm' | 'md' | 'lg' | 'xl', number>;
spacing: Record<'xs' | 'sm' | 'md' | 'lg' | 'xl', number>;
// Values used for box-shadow
shadows: Record<'xs' | 'sm' | 'md' | 'lg' | 'xl', string>;
// Breakpoints used in some components to add responsive styles
breakpoints: Record<'xs' | 'sm' | 'md' | 'lg' | 'xl', number>;
// Styles added to buttons with `:active` pseudo-class
activeStyles: CSSObject;
// h1-h6 styles, used in Title and TypographyStylesProvider components
headings: {
fontFamily: CSSProperties['fontFamily'];
fontWeight: CSSProperties['fontWeight'];
sizes: {
// See heading options below
h1: Heading;
h2: Heading;
h3: Heading;
h4: Heading;
h5: Heading;
h6: Heading;
};
};
// theme functions, see in theme functions guide
fn: MantineThemeFunctions;
// Left to right or right to left direction, see RTL Support guide to learn more
dir: 'ltr' | 'rtl';
// Default loader used in Loader and LoadingOverlay components
loader: 'oval' | 'bars' | 'dots';
// Default date format used in DatePicker and DateRangePicker components
dateFormat: string;
// Default dates formatting locale used in every @mantine/dates component
datesLocale: string;
// defaultProps, styles and classNames for components
components: ComponentsOverride;
// Add your own custom properties on Mantine theme
other: Record<string, any>;
}
interface Heading {
fontSize: CSSProperties['fontSize'];
fontWeight: CSSProperties['fontWeight'];
lineHeight: CSSProperties['lineHeight'];
}

Usage

To customize theme, pass theme override object to MantineProvider theme prop. Theme override will be deeply merged with default theme.

import { MantineProvider } from '@mantine/core';
function Demo() {
return (
<MantineProvider
withGlobalStyles
withNormalizeCSS
theme={{
colorScheme: 'light',
colors: {
// Add your color
deepBlue: ['#E9EDFC', '#C1CCF6', '#99ABF0' /* ... */],
// or replace default theme color
blue: ['#E9EDFC', '#C1CCF6', '#99ABF0' /* ... */],
},
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: 30 },
},
},
}}
>
<App />
</MantineProvider>
);
}

Theme properties

colorScheme

theme.colorScheme determines which color scheme will be used in your application. It can be either light or dark, default value is light. See dark theme guide to learn how to setup dark theme in your application.

focusRing

theme.focusRing controls focus ring styles, it supports the following values:

  • auto (default) – focus ring is visible only when user navigates with keyboard, this is default browser behavior for native interactive elements
  • always – focus ring is visible when user navigates with keyboard and mouse
  • never – focus ring is always hidden, it is not recommended – users who navigate with keyboard will not have visual indication of current focused element
Focus ring: auto
Focus ring: always
Focus ring: never

defaultRadius

theme.defaultRadius controls default border-radius of all Mantine components (Button, TextInput, ThemeIcon, etc.), default value is sm. It accepts 'xs' | 'sm' | 'md' | 'lg' | 'xl' (key of theme.radius) or a number to set border-radius in px. For example, to remove border-radius from all elements set defaultRadius: 0:

import { MantineProvider, Button } from '@mantine/core';
function Demo() {
return (
<MantineProvider theme={{ defaultRadius: 0 }}>
<Button>With 0px border-radius</Button>
<Button radius="xl">Default radius can be overridden with radius prop</Button>
</MantineProvider>
);
}

colors

Mantine theme has the following properties associated with colors:

  • theme.white used for body and overlays (Modal, Popover) background when theme.colorScheme is light, default value is #fff
  • theme.black used as color for all text when theme.colorScheme is light, default value is #000
  • theme.colors, theme.primaryColor and theme.primaryShade properties are described in the separate guide

activeStyles

theme.activeStyles lets you override styles added to buttons with :active pseudo-class:

import { Button, MantineProvider } from '@mantine/core';
function Demo() {
return (
<MantineProvider theme={{ activeStyles: { transform: 'scale(0.95)' } }}>
<Button>Press me</Button>
</MantineProvider>
);
}

defaultGradient

theme.defaultGradient defines default gradient value for components that support variant="gradient" (Button, ThemeIcon, etc.):

import { MantineProvider, Button, Group } from '@mantine/core';
function Demo() {
return (
<Group position="center">
<Button variant="gradient">Default gradient button</Button>
<MantineProvider
inherit
theme={{
defaultGradient: {
from: 'orange',
to: 'red',
deg: 45,
},
}}
>
<Button variant="gradient">Gradient from provider</Button>
</MantineProvider>
</Group>
);
}

loader

theme.loader controls default loader that will be displayed by Loader and LoadingOverlay components:

Loader: oval
Loader: bars
Loader: dots

respectReduceMotion

theme.respectReduceMotion allows to disregard user OS settings and play animations for users who do not want that:

cursorType

theme.cursorType determines which cursor type will native controls have. If it is set to pointer then Checkbox, Radio, NativeSelect and other native elements will have cursor: pointer style:

dateFormat

With theme.dateFormat you can configure default date format for DatePicker and DateRangePicker components:

datesLocale

theme.datesLocale determines which locale will be used for all @mantine/dates packages by default. Note that you should also import dayjs/locale/[locale] to load localization files:

dir

theme.dir controls text direction, you will need to set it if you need RTL support, follow RTL guide to get started.

other

With theme.other you can add any amount of extra properties to theme:

import { MantineProvider } from '@mantine/core';
function Demo() {
return (
<MantineProvider
theme={{
other: {
charcoal: '#333333',
primaryHeadingSize: 45,
fontWeights: {
bold: 700,
extraBold: 900,
},
},
}}
>
<App />
</MantineProvider>
);
}

To specify theme.other type, add file with the following declaration:

declare module '@mantine/core' {
export interface MantineThemeOther {
myCustomProperty: string;
myCustomFunction: () => void;
}
}

Store theme override object in a variable

To store theme override object in a variable use MantineThemeOverride type:

import { MantineThemeOverride, MantineProvider } from '@mantine/core';
const myTheme: MantineThemeOverride = {
colorScheme: 'light',
primaryColor: 'orange',
defaultRadius: 0,
};
function Demo() {
return (
<MantineProvider theme={myTheme} withGlobalStyles withNormalizeCSS>
<App />
</MantineProvider>
);
}

use-mantine-theme hook

use-mantine-theme hook returns theme from MantineProvider context or default theme if you did not provide theme override:

import { useMantineTheme } from '@mantine/core';
function Demo() {
const theme = useMantineTheme();
return <div style={{ background: theme.colors.blue[5] }} />;
}

MantineTheme type

You can import MantineTheme type from @mantine/core package:

import { useMantineTheme, MantineTheme } from '@mantine/core';
function getColor(theme: MantineTheme) {
return theme.colors.blue[5];
}
function Demo() {
const theme = useMantineTheme();
return <div style={{ background: getColor(theme) }} />;
}