Theming

By default all Mantine components use the default theme. You can extend and customize theme on top level with MantineProvider or on individual component level with theme override.

MantineProvider

MantineProvider component allows you to change theme globally. It is not required if you decide to stick with default theme:

import React from 'react';
import { MantineProvider, Button } from '@mantine/core';

function App() {
  return <Button>My app button</Button>;
}

// Custom theme is applied to all components in App
function WithProvider() {
  return (
    <MantineProvider theme={{ fontFamily: 'Open Sans' }}>
      <App />
    </MantineProvider>
  );
}

// Default theme is used in all components in App
function NoProvider() {
  return <App />;
}

Theme object

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

Theme shape:

interface MantineTheme {
  colorScheme: 'light' | 'dark';
  white: string;
  black: string;
  colors: Record<string, Tuple<string, 10>>;
  fontFamily: CSSProperties['fontFamily'];
  lineHeight: CSSProperties['lineHeight'];
  transitionTimingFunction: CSSProperties['transitionTimingFunction'];
  fontFamilyMonospace: CSSProperties['fontFamily'];
  primaryColor: string;

  fontSizes: Record<'xs' | 'sm' | 'md' | 'lg' | 'xl', number>;
  radius: Record<'xs' | 'sm' | 'md' | 'lg' | 'xl', number>;
  spacing: Record<'xs' | 'sm' | 'md' | 'lg' | 'xl', number>;
  shadows: Record<'xs' | 'sm' | 'md' | 'lg' | 'xl', string>;

  headings: {
    fontFamily: CSSProperties['fontFamily'];
    fontWeight: CSSProperties['fontWeight'];
    sizes: {
      h1: { fontSize: CSSProperties['fontSize']; lineHeight: CSSProperties['lineHeight'] };
      h2: { fontSize: CSSProperties['fontSize']; lineHeight: CSSProperties['lineHeight'] };
      h3: { fontSize: CSSProperties['fontSize']; lineHeight: CSSProperties['lineHeight'] };
      h4: { fontSize: CSSProperties['fontSize']; lineHeight: CSSProperties['lineHeight'] };
      h5: { fontSize: CSSProperties['fontSize']; lineHeight: CSSProperties['lineHeight'] };
      h6: { fontSize: CSSProperties['fontSize']; lineHeight: CSSProperties['lineHeight'] };
    };
  };
}

Default theme

import { DEFAULT_THEME } from '@mantine/core';

View full default theme source on Github

You can use default theme object in tests or storybook for simplicity. Do not use DEFAULT_THEME for styling as it is not connected to MantineProvider.

Extending theme

You can change theme for all components. To do so wrap your application with MantineProvider component. Theme is deeply merged, every property that is not specified will be taken from default theme.

import React from 'react';
import { MantineProvider } from '@mantine/core';

function YourApp() {
  return (
    <MantineProvider
      theme={{
        fontFamily: 'Open Sans, sans-serif',
        lineHeight: 1.2,
        primaryColor: 'indigo',
      }}
    >
      <App />
    </MantineProvider>
  );
}

Colors

Mantine uses open-color in default theme with some additions. Each color has 10 shades.

Colors are exposed on theme object as an array of strings, you can access color shade by color name and index (0-9), colors with larger index are darker:

theme.colors.red[5];
theme.colors.gray[9];
theme.colors.blue[0];

Add or replace colors

You can add any amount of extra colors by extending theme.colors with MantineProvider. This will allow you to use these colors with all components which support color change, for example, Button, Badge or Switch.

Note that all colors that are added should always include 10 shades. You can use some of these tools to generate or copy ready color palettes:

• Themera
• Material Design Colors
• Omatsuri
• Smart Swatch
• Palx

import React from 'react';
import { Badge, Button, MantineProvider, Switch } from '@mantine/core';

function Demo() {
  return (
    <MantineProvider theme={{
      colors: {
        'deep-blue': ['#E9EDFC', '#C1CCF6', '#99ABF0', '#7189EA', '#4968E4', '#2147DE', '#1A39B2', '#142B85', '#0D1D59', '#070E2C'],
        asphalt: ['#F0F4F5', '#D4E0E2', '#B9CCD0', '#9EB8BD', '#82A4AB', '#679098', '#52747A', '#3E575B', '#293A3D', '#151D1E']
      },
    }}>
      <Button color="deep-blue">Deep blue button</Button>

      <Badge color="asphalt" variant="filled">
        Asphalt badge
      </Badge>

      <Switch
        color="deep-blue"
        label="Deep blue switch"
        defaultChecked
      />
    </MantineProvider>
  );
}

Primary color

Default primary color is blue, you can change it to any color defined in theme.colors. Primary color is used:

• in some components to determine color value if component didn't receive color prop;
• to define focus styles for all interactive elements.

For example, Button Component by default will use theme.primaryColor (press any key on keyboard to see focus ring):

import React from 'react';
import { Button, MantineProvider } from '@mantine/core';

function Demo() {
  return (
    <MantineProvider theme={{ primaryColor: 'teal' }}>
      <Button>Primary button</Button>
      <Button color="red">Red button</Button>
    </MantineProvider>
  );
}

Fonts and text styles

By default Mantine uses system fonts. It brings fast and familiar experience to users. You can change fonts and other text styles for headings, code and all other components:

• theme.fontFamilyMonospace – controls components with monospace font-family, for example, Code and Kbd
• theme.fontFamily – controls font-family in all other cases
• theme.lineHeight – controls line-height property in all components except headings
• theme.fontSizes – controls font-size in all components except headings
• theme.headings – controls font-family, line-heigh and font-size of h1-h6 tags in Title and TypographyStylesProvider components

import React from 'react';
import { Button, Code, Title, MantineProvider } from '@mantine/core';

function Demo() {
  return (
    <MantineProvider theme={{
      fontFamily: 'Verdana, sans-serif',
      fontFamilyMonospace: 'Courier, monospace',
      headings: { fontFamily: 'Georgia, serif' },
    }}>
      <Title order={3}>Georgia or serif title</Title>
      <Button>Verdana button</Button>
      <Code>Courier Code</Code>
    </MantineProvider>
  );
}

Spacing, radius and shadows

By default Mantine supports 5 sizes for spacing, radius and shadows: xs, sm, md, lg, xl. These values are exposed on theme:

• theme.spacing – general spacing values used for paddings and margins, for example, to set padding on Paper or Container components or to calculate margins in TypographyStylesProvider component.
• theme.shadows – box-shadow values – used with components which extend Paper: Modal, Menu and others
• theme.radius – border-radius values – used in all components which support radius: Paper, Button, Input and others

Example with Paper component (padding is set with theme.spacing):

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

You can change size values by setting corresponding properties. In this example:

• xs and xl values from theme will be overwritten
• sm, md and lg values will be used from default theme

import React from 'react';
import { Button, Code, MantineProvider, Title } from '@mantine/core';

function YourApp() {
  return (
    <MantineProvider
      theme={{
        spacing: {
          xs: 2,
          xl: 20,
        },
      }}
    >
      <Title order={3}>Georgia or serif title</Title>
      <Button>Verdana button</Button>
      <Code>Courier Code</Code>
    </MantineProvider>
  );
}

Nested MantineProviders

If some parts of your application require different theme styles you can wrap them in another MantineProvider. Nested MantineProvider components do not inherit theme properties from parents and merge theme prop with default theme.

import React from 'react';
import { Button, MantineProvider, Text } from '@mantine/core';

function Demo() {
  return (
    <MantineProvider theme={{ fontFamily: 'Georgia, serif' }}>
      <Text style={{ textAlign: 'center', marginBottom: 10 }}>Georgia or serif text</Text>

      <MantineProvider theme={{ fontFamily: 'Verdana, sans-serif' }}>
        <Button>Verdana button</Button>
      </MantineProvider>
    </MantineProvider>
  );
}

Overriding theme on component level

Each Mantine component that uses theme supports theme override with themeOverride prop:

import React from 'react';
import { Button } from '@mantine/core';

function Demo() {
  return (
    <Button themeOverride={{ fontFamily: 'Verdana, sans-serif' }}>
      Verdana button
    </Button>
  );
}

Dark theme

Mantine has native support for dark theme. Dark theme is available for all components. You can view default dark theme for each component by changing color scheme in upper right corner or with keyboard shortcut ⌘ + J on MacOS and Ctrl + J on other systems.

Read everything about dark theme in dark theme guide.

Use mantine theme with react-jss

All Mantine components are built with react-jss. We recommend to use react-jss to style the rest of your application as it provides you with the most convenient way to utilize Mantine theme, but it is not required – you can use any other styling tools and languages.

use-mantine-theme hook

Hook returns theme from MantineProvider context or default theme if you did not wrap application with MantineProvider.

import { useMantineTheme } from '@mantine/core';

function Component() {
  const theme = useMantineTheme();
  return <div style={{ background: theme.colors.blue[5] }} />;
}

Theming context

If your application is wrapped with MantineProvider you can utilize theming context in createUseStyles:

import React from 'react';
import { createUseStyles } from 'react-jss';
import { theming } from '@mantine/core';

const useStyles = createUseStyles(
  (theme) => ({
    wrapper: {
      background: theme.colors.gray[5],
    },
  }),
  { theming }
);

function YourComponent() {
  const classes = useStyles();
  return <div className={classes.wrapper} />;
}

Theme as function value

This way will work in all cases no matter if you use MantineProvider or not.

import React from 'react';
import { createUseStyles } from 'react-jss';
import { useMantineTheme } from '@mantine/core';

const useStyles = createUseStyles({
  wrapper: ({ theme }) => ({
    background: theme.colors.gray[5],
  }),
});

function YourComponent() {
  const classes = useStyles({ theme: useMantineTheme() });
  return <div className={classes.wrapper} />;
}

Utility functions

@mantine/core package has several utility function that will help you work with Mantine theme in jss.

getFocusStyles

Returns mantine focus styles in jss format for interactive elements. Focus styles are visible only when user navigates with keyboard.

import { createUseStyles } from 'react-jss';
import { getFocusStyles, theming } from '@mantine/core';

createUseStyles(
  (theme) => ({
    button: {
      ...getFocusStyles(theme),
      color: 'red',
    },
  }),
  { theming }
);

getFontStyles

Returns font styles from theme with font smoothing:

import { createUseStyles } from 'react-jss';
import { getFontStyles, theming } from '@mantine/core';

createUseStyles(
  (theme) => ({
    wrapper: {
      ...getFontStyles(theme),
      color: 'red',
    },
  }),
  { theming }
);

TypeScript

@mantine/core package exports types:

• MantineSize – 'xs' | 'sm' | 'md' | 'lg' | 'xl'
• MantineNumberSize – MantineSize | number
• MantineSizes – Record<MantineSize, number>
• MantineTheme – theme object interface
• MantineThemeOverride – theme override options