group | title | slug | order | search |
---|---|---|---|---|
theming |
Theme object |
/theming/theme-object/ |
0 |
Theme object, use-mantine-theme, theme overrides, MantineTheme type |
import { ThemeDemos } from '@mantine/demos';
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;
// Global styles
globalStyles: (theme: MantineTheme) => CSSObject;
// Add your own custom properties on Mantine theme
other: Record<string, any>;
}
interface Heading {
fontSize: CSSProperties['fontSize'];
fontWeight: CSSProperties['fontWeight'];
lineHeight: CSSProperties['lineHeight'];
}
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.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.
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 elementsalways
– focus ring is visible when user navigates with keyboard and mousenever
– focus ring is always hidden, it is not recommended – users who navigate with keyboard will not have visual indication of current focused element
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>
);
}
Mantine theme has the following properties associated with colors:
theme.white
used for body and overlays (Modal, Popover) background whentheme.colorScheme
islight
, default value is#fff
theme.black
used as color for all text whentheme.colorScheme
islight
, default value is#000
theme.colors
,theme.primaryColor
andtheme.primaryShade
properties are described in the separate guide
theme.activeStyles
lets you override styles added to buttons with :active
pseudo-class:
theme.defaultGradient
defines default gradient value for components that support variant="gradient"
(Button, ThemeIcon, etc.):
theme.loader
controls default loader that will be displayed by Loader and LoadingOverlay components:
theme.respectReduceMotion
allows to disregard user OS settings and play animations for users who do not want that:
<Demo data={ThemeDemos.respectReduceMotion} demoProps={{ toggle: true }} />
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:
<Demo data={ThemeDemos.cursorType} demoProps={{ toggle: true }} />
With theme.dateFormat
you can configure default date format for DatePicker and DateRangePicker
components:
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:
theme.dir
controls text direction, you will need to set it if you need RTL support, follow RTL guide to get started.
theme.globalStyles
adds global styles, see global styles guide to learn more.
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;
}
}
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 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] }} />;
}
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) }} />;
}