Learn the basics

This guide will help you get familiar with core Mantine concepts. Please read this guide, theming and styles sections before starting development to learn about all available theming and styling features.

Getting help

Mantine has a very friendly community, we are always happy to help you get started:

Using documentation

Mantine documentation includes more than 150 pages, to use it efficiently remember 2 keyboard shortcuts:

  • ⌘ + K or Ctrl + K – focus search field, searching components and hooks is the best way to jump straight to the page you are looking for.
  • ⌘ + J or Ctrl + J – toggle color scheme (light/dark). All components support both light and dark color schemes, using this shortcut is the easiest way to preview both color schemes.
  • ⌘ + Shift + L or Ctrl + Shift + L – toggle text direction (LTR/RTL)

Theming

Theme object supports changing colors, spacing, box-shadows, font families, font sizes and many other properties. To configure theme, wrap your app with a MantineProvider component:

import { MantineProvider } from '@mantine/core';
function Demo() {
return (
<MantineProvider
theme={{
// Override any other properties from default theme
fontFamily: 'Open Sans, sans serif',
spacing: { xs: '1rem', sm: '1.2rem', md: '1.8rem', lg: '2.2rem', xl: '2.8rem' },
}}
>
<App />
</MantineProvider>
);
}

Dark color scheme

All Mantine components support light and dark color scheme out of the box. To learn how to implement color scheme changes via context follow dark theme guide.

import { MantineProvider } from '@mantine/core';
function Demo() {
return (
<MantineProvider theme={{ colorScheme: 'dark' }}>
<App />
</MantineProvider>
);
}

Writing styles

createStyles

Mantine is built with a css-in-js library based on emotion. You can use any other styling solution but we recommend working with createStyles to avoid styles collisions.

Core createStyles features overview:

createStyles demo
import { createStyles, getStylesRef, rem } from '@mantine/core';
const useStyles = createStyles((theme) => ({
wrapper: {
// subscribe to color scheme changes right in your styles
backgroundColor: theme.colorScheme === 'dark' ? theme.colors.dark[5] : theme.colors.gray[1],
maxWidth: rem(400),
width: '100%',
height: rem(180),
display: 'flex',
alignItems: 'center',
justifyContent: 'center',
marginLeft: 'auto',
marginRight: 'auto',
borderRadius: theme.radius.sm,
// Dynamic media queries, define breakpoints in theme, use anywhere
[theme.fn.smallerThan('sm')]: {
// Child reference in nested selectors via ref
[`& .${getStylesRef('child')}`]: {
fontSize: theme.fontSizes.xs,
},
},
},
child: {
// assign ref to element
ref: getStylesRef('child'),
backgroundColor: theme.colorScheme === 'dark' ? theme.colors.dark[8] : theme.white,
padding: theme.spacing.md,
borderRadius: theme.radius.sm,
boxShadow: theme.shadows.md,
color: theme.colorScheme === 'dark' ? theme.white : theme.black,
},
}));
function Demo() {
const { classes } = useStyles();
return (
<div className={classes.wrapper}>
<div className={classes.child}>createStyles demo</div>
</div>
);
}

Styling components internals with Styles API

Styles API lets you add styles to any internal part of a component with inline styles or classes:

20%
50%
80%
import { Slider, rem } from '@mantine/core';
const marks = [
{ value: 20, label: '20%' },
{ value: 50, label: '50%' },
{ value: 80, label: '80%' },
];
function Demo() {
return (
<Slider
defaultValue={40}
marks={marks}
labelTransition="fade"
size={2}
styles={(theme) => ({
track: {
backgroundColor:
theme.colorScheme === 'dark' ? theme.colors.dark[3] : theme.colors.blue[1],
},
mark: {
width: rem(6),
height: rem(6),
borderRadius: rem(6),
transform: `translateX(-${rem(3)}) translateY(-${rem(2)})`,
borderColor: theme.colorScheme === 'dark' ? theme.colors.dark[3] : theme.colors.blue[1],
},
markFilled: {
borderColor: theme.colors.blue[6],
},
markLabel: { fontSize: theme.fontSizes.xs, marginBottom: rem(5), marginTop: 0 },
thumb: {
height: rem(16),
width: rem(16),
backgroundColor: theme.white,
borderWidth: rem(1),
boxShadow: theme.shadows.sm,
},
})}
/>
);
}

Components props

Color prop

Mantine components work with colors defined in theme.colors. theme.colors is an object that contains an array of 10 shades per each color. To use predefined colors in components set color prop:

<Badge color="teal" />
<Button color="violet" />

You can extend theme with any amount of your colors:

import { MantineProvider } from '@mantine/core';
function Demo() {
return (
<MantineProvider
theme={{
// Theme is deeply merged with default theme
colors: {
// Add your color
'deep-blue': ['#E9EDFC', '#C1CCF6', '#99ABF0' /* 7 other shades */],
// or replace default theme color
blue: ['#E9EDFC', '#C1CCF6', '#99ABF0' /* 7 other shades */],
},
}}
>
<App />
</MantineProvider>
);
}

Note that component appearance usually depends on variant prop and current theme.colorScheme.

Sizes

Most Mantine components support size prop with xs, sm, md, lg and xl values:

<Button size="xl" />
<Badge size="xs" />

The size prop controls various css properties across all supported components. In some components where size is associated with only one value, you can set it in px:

<Slider size="xs" /> // Predefined xs size
<Slider size={32} /> // -> 2rem track height, other parts are scaled from this value

Spacing and padding

Components that have padding get values from theme.spacing, default values are:

{
xs: '0.625rem',
sm: '0.75rem',
md: '1rem',
lg: '1.25rem',
xl: '1.5rem',
}

To change these values set spacing property on theme:

import { MantineProvider } from '@mantine/core';
function Demo() {
return (
<MantineProvider
theme={{ spacing: { xs: '1rem', sm: '1.2rem', md: '1.8rem', lg: '2.2rem', xl: '2.8rem' } }}
>
<App />
</MantineProvider>
);
}

Later when you use Mantine components you can reference these values in spacing or other similar props or set the spacing in px:

<Group spacing="md" /> // -> md spacing from theme.spacing
<Group spacing={32} /> // 2rem spacing

Shadows

Components that use the box-shadow property get values from theme.shadows, default values are:

{
xs: '0 0.0625rem 0.1875rem rgba(0, 0, 0, 0.05), 0 0.0625rem 0.125rem rgba(0, 0, 0, 0.1)',
sm: '0 0.0625rem 0.1875rem rgba(0, 0, 0, 0.05), rgba(0, 0, 0, 0.05) 0 0.625rem 0.9375rem -0.3125rem, rgba(0, 0, 0, 0.04) 0 0.4375rem 0.4375rem -0.3125rem',
md: '0 0.0625rem 0.1875rem rgba(0, 0, 0, 0.05), rgba(0, 0, 0, 0.05) 0 1.25rem 1.5625rem -0.3125rem, rgba(0, 0, 0, 0.04) 0 0.625rem 0.625rem -0.3125rem',
lg: '0 0.0625rem 0.1875rem rgba(0, 0, 0, 0.05), rgba(0, 0, 0, 0.05) 0 1.75rem 1.4375rem -0.4375rem, rgba(0, 0, 0, 0.04) 0 0.75rem 0.75rem -0.4375rem',
xl: '0 0.0625rem 0.1875rem rgba(0, 0, 0, 0.05), rgba(0, 0, 0, 0.05) 0 2.25rem 1.75rem -0.4375rem, rgba(0, 0, 0, 0.04) 0 1.0625rem 1.0625rem -0.4375rem',
}

To change these values set the shadows property on theme:

import { MantineProvider } from '@mantine/core';
function Demo() {
return (
<MantineProvider
theme={{
shadows: {
xs: '0.0625rem 0.0625rem 0.0625rem rgba(0, 0, 0, 0.3)',
sm: '0.0625rem 0.0625rem 0.0625rem rgba(0, 0, 0, 0.4)',
md: '0.1875rem 0.1875rem 0.0625rem rgba(0, 0, 0, 0.4)',
lg: '0.1875rem 0.1875rem 0.0625rem 0.5rem rgba(0, 0, 0, 0.4)',
xl: '0.1875rem 0.1875rem 0.0625rem 1rem rgba(0, 0, 0, 0.4)',
},
}}
>
<App />
</MantineProvider>
);
}

Later when you use Mantine components you can reference these values in shadow prop or define your own shadow:

<Paper shadow="xl" /> // -> xl shadow from theme.shadows
<Paper shadow="0.0625rem 0.1875rem 0.5rem rgba(0, 0, 0, 0.4)" /> // -> your own shadow not related to theme.shadows

Getting element ref

You can get ref of most components with their ref prop:

import { useRef } from 'react';
import { Button, Paper, TextInput } from '@mantine/core';
function Demo() {
const buttonRef = useRef<HTMLButtonElement>(null);
const paperRef = useRef<HTMLDivElement>(null);
const inputRef = useRef<HTMLInputElement>(null);
return (
<>
<Button ref={buttonRef} />
<Paper ref={paperRef} />
<TextInput ref={inputRef} />
</>
);
}

Server side rendering

To setup server side rendering follow one of these guides

TypeScript

Exported types

@mantine/core package export types to help you build components and styles with TypeScript:

  • MantineTheme – theme interface defined in MantineProvider.
  • ColorScheme – union of 'light' | 'dark'.
  • MantineColor – union of all default colors, also accepts any string.
  • MantineGradient – gradient interface used in Button, ThemeIcon and other components.
  • MantineShadow – union of all default shadows.
  • MantineSize – union of 'xs' | 'sm' | 'md' | 'lg' | 'xl'.
  • MantineNumberSize – union of MantineSize | number.

Components props

You can import props type of any component by adding Props to the component name:

import type { ButtonProps } from '@mantine/core';