Learn the basics

This guide will help you get familiar with core Mantine concepts. Please read this guide and theming section before staring development to learn about all available theming features and components props.

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 so 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 color schemes and using this shortcut is the easiest way to preview both color schemes.

Mantine packages

  • @mantine/hooks – collection of 30+ react hooks for state and UI management.
  • @mantine/stylesemotion based css-in-js library that is used in all Mantine components. Usually this package is installed automatically and exported from @mantine/core – there is no need to install it separately, learn more about createStyles here.
  • @mantine/core – core components library – 100+ components, exports everything from @mantine/styles.
  • @mantine/notifications – a fully featured notifications system.
  • @mantine/prismcode highlight built with prism-react-renderer.
  • @mantine/rte – a Quill based rich text editor.
  • @mantine/dropzone – manages files drag 'n' drop of files to an area or the entire screen.
  • @mantine/ssrserver side rendering utilities.
  • @mantine/next – components and ssr utils for Next.js integration.
  • gatsby-plugin-mantineGatsby plugin to setup ssr.
  • @mantine/eslint-config – ESLint and Prettier configuration that the Mantine project uses.


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

import { MantineProvider } from '@mantine/core';
export function Demo() {
return (
// Override any other properties from default theme
fontFamily: 'Open Sans, sans serif',
spacing: { xs: 15, sm: 20, md: 25, lg: 30, xl: 40 },
<App />

Learn more about MantineProvider and extending theme.

Dark color scheme

All Mantine components support light and dark color scheme out of the box. You can edit the details of each color scheme via MantineProvider:

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

To learn how to implement color scheme changes via context follow dark theme guide.

Writing styles


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.

createStyles usage demo:

createStyles demo
import { createStyles } from '@mantine/core';
const useStyles = createStyles((theme, _params, getRef) => {
const child = getRef('child');
return {
wrapper: {
// subscribe to color scheme changes right in your styles
backgroundColor: theme.colorScheme === 'dark' ? theme.colors.dark[5] : theme.colors.gray[1],
maxWidth: 400,
width: '100%',
height: 180,
display: 'flex',
alignItems: 'center',
justifyContent: 'center',
marginLeft: 'auto',
marginRight: 'auto',
borderRadius: theme.radius.sm,
// Dynamic media queries, define breakpoints in theme, use anywhere
[`@media (max-width: ${theme.breakpoints.sm}px)`]: {
// Type safe child reference in nested selectors via ref
[`& .${child}`]: {
fontSize: theme.fontSizes.xs,
child: {
// assign ref to element
ref: 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>

Styling components internals with Styles API

Styles API lets you add styles to any internal part of a component:

styles={(theme) =>({
track: {
theme.colorScheme === 'dark' ? theme.colors.dark[3] : theme.colors.blue[1],
mark: {
width: 6,
height: 6,
borderRadius: 6,
transform: 'translateX(-3px) translateY(-2px)',
borderColor: theme.colorScheme === 'dark' ? theme.colors.dark[3] : theme.colors.blue[1],
markFilled: {
borderColor: theme.colors.blue[6],
markLabel: { fontSize: theme.fontSizes.xs, marginBottom: 5, marginTop: 0 },
thumb: {
height: 16,
width: 16,
backgroundColor: theme.white,
borderWidth: 1,
boxShadow: theme.shadows.sm,

Components props

Shared props

All Mantine components support these props:

  • className – adds class to root element.
  • style – adds style to root element.
  • Margins:
    • m – sets margin property on root element.
    • my – sets margin-top and margin-bottom properties on root element.
    • mx – sets margin-right and margin-left properties on root element.
    • mt – sets margin-top property on root element.
    • mb – sets margin-bottom property on root element.
    • ml – sets margin-left property on root element.
    • mr – sets margin-right property on root element.
import { Button } from '@mantine/core';
function Demo() {
return (
<Button className="my-button" style={{ backgroundColor: '#fff' }} mx={20}>
My button

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:

// Theme is deeply merged with default theme
colors: {
// Add your color
'deep-blue': ['#E9EDFC', '#C1CCF6', '#99ABF0' /* ... */],
// or replace default theme color
blue: ['#E9EDFC', '#C1CCF6', '#99ABF0' /* ... */],
<YourApp />

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


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={20} /> // -> 20px 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: 10, sm: 12, md: 16, lg: 20, xl: 24 }

To change these values set spacing property on theme:

<MantineProvider theme={{ spacing: { xs: 15, sm: 20, md: 25, lg: 30, xl: 40 } }}>
<YourApp />

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

<Paper padding="xl" /> // -> xl padding from theme.spacing
<Paper padding={30} /> // -> 30px padding
<Group spacing="md" /> // -> md spacing from theme.spacing
<Group spacing={40} /> // 40px spacing


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

xs: '0 1px 3px rgba(0, 0, 0, 0.05), 0 1px 2px rgba(0, 0, 0, 0.1)',
sm: '0 1px 3px rgba(0, 0, 0, 0.05), rgba(0, 0, 0, 0.05) 0px 10px 15px -5px, rgba(0, 0, 0, 0.04) 0px 7px 7px -5px',
md: '0 1px 3px rgba(0, 0, 0, 0.05), rgba(0, 0, 0, 0.05) 0px 20px 25px -5px, rgba(0, 0, 0, 0.04) 0px 10px 10px -5px',
lg: '0 1px 3px rgba(0, 0, 0, 0.05), rgba(0, 0, 0, 0.05) 0px 28px 23px -7px, rgba(0, 0, 0, 0.04) 0px 12px 12px -7px',
xl: '0 1px 3px rgba(0, 0, 0, 0.05), rgba(0, 0, 0, 0.05) 0px 36px 28px -7px, rgba(0, 0, 0, 0.04) 0px 17px 17px -7px',

To change these values set the shadows property on theme:

shadows: {
xs: '1px 1px 1px rgba(0, 0, 0, 0.3)',
sm: '1px 1px 4px rgba(0, 0, 0, 0.4)',
md: '3px 3px 4px rgba(0, 0, 0, 0.4)',
lg: '3px 3px 4px 5px rgba(0, 0, 0, 0.4)',
xl: '3px 3px 4px 15px rgba(0, 0, 0, 0.4)',
<YourApp />

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="1px 3px 4px rgba(0, 0, 0, 0.4)" /> // -> your own shadow not related to theme.shadows

Default spacing and shadow demo

Paper is the most basic ui component
Use it to create cards, dropdowns, modals and other components that require background with shadow
<Paper padding="md" shadow="xs">
<Text>Paper is the most basic ui component</Text>
Use it to create cards, dropdowns, modals and other components that require background
with shadow

Polymorphic components

Some Mantine components support changing root element with component prop, you can pass html element or React component to the prop:

// with html element
<Text component="a" href="https://mantine.dev">
My link text
// with custom component
import { Link } from 'react-router-dom';
<Text component={Link} to="/hello">
My link text

To use Mantine components with Next.js Link:

  • set component prop to a
  • wrap it with Link
import Link from 'next/link';
<Link href="/hello">
<Button component="a">Next link button</Button>

If you use polymorphic with TypeScript you will also need to set type for full types coverage, otherwise you will have untyped event handlers and ref props:

// with html component
<Button<'a'> component="a" />;
// with custom component
import { Link } from 'react-router-dom';
<Button<typeof Link> component="a" />;

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
const paperRef = useRef(); // -> HTMLDivElement
const inputRef = useRef(); // -> HTMLInputElement
return (
<Button ref={buttonRef} />
<Paper ref={paperRef} />
<TextInput ref={inputRef} />

Server side rendering

To setup server side rendering follow one of these guides


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';

Polymorphic components types

@mantine/core package exports PolymorphicRef and PolymorphicComponentProps types to help you build custom components with ref forwarding:

import { forwardRef } from 'react';
import type { PolymorphicRef, PolymorphicComponentProps } from '@mantine/core';
// Define all component specific props here
interface _TextProps {
bold: boolean;
type TextProps<C extends React.ElementType> = PolymorphicComponentProps<C, _TextProps>;
type TextComponent = <C extends React.ElementType = 'div'>(
props: TextProps<C>
) => React.ReactElement;
const Text: TextComponent = forwardRef(
<C extends React.ElementType = 'div'>(
{ bold, component, ...others }: TextProps<C>,
ref: PolymorphicRef<C>
) => {
const Element = component || 'div';
return <Element style={{ fontWeight: bold ? 700 : 400 }} {...others} />
// Default div text, props will have type React.ComponentPropsWithoutRef<'div'> & _TextProps
<Text bold>Bold text</Text>
// Text as an anchor, props will have type React.ComponentPropsWithoutRef<'a'> & _TextProps
<Text component="a" href="https://mantine.dev">Mantine website</Text>
// Text as component, props will have type React.ComponentPropsWithoutRef<typeof Link> & _TextProps
import { Link } from 'react-router-dom';
<Text component={Link} to="/route">Router link</Text>
Build fully functional accessible web applications faster than ever
Your feedback is most valuable contribution to the project, please share how you use Mantine, what features are missing and what is done good
Leave feedback