Colors

Mantine includes 14 color palettes with 10 shades each, plus the scheme-aware neutral color. The palettes use OKLCH with shared lightness values, so colored controls have consistent brightness across hues.

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

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

function Demo() {
  const theme = useMantineTheme();

  return (
    <div
      style={{
        backgroundColor: theme.colors.blue[1],
        color: theme.colors.blue[9],
      }}
    >
      This is a blue theme
    </div>
  );
}

Colors are also exposed as CSS variables:

.demo {
  color: var(--mantine-color-red-5);
  background: var(--mantine-color-grape-9);
  border: 1px solid var(--mantine-color-blue-1);
}

OKLCH CSS variables

In v10, --mantine-color-* variables emit oklch(L C H) strings instead of hex/RGB. Code that reads these values and parses them as hex or RGB must be updated. See the 9.x → 10.x migration guide for details and the one-line v9 opt-out.

Adding extra colors

You can add any number of extra colors to the theme.colors object. This will allow you to use them in all components that support the color prop, for example Button, Badge, and Switch.

import { Group, Button, MantineProvider, createTheme } from '@mantine/core';

const theme = createTheme({
  colors: {
    'ocean-blue': ['#7AD1DD', '#5FCCDB', '#44CADC', '#2AC9DE', '#1AC2D9', '#11B7CD', '#09ADC3', '#0E99AC', '#128797', '#147885'],
    'bright-pink': ['#F0BBDD', '#ED9BCF', '#EC7CC3', '#ED5DB8', '#F13EAF', '#F71FA7', '#FF00A1', '#E00890', '#C50E82', '#AD1374'],
  },
});

function Demo() {
  return (
    <MantineProvider theme={theme}>
      <Group>
        <Button color="ocean-blue">Ocean blue button</Button>
        <Button color="bright-pink" variant="filled">
          Bright pink button
        </Button>
      </Group>
    </MantineProvider>
  );
}

10 shades per color

A colors override must include at least 10 shades per color. Otherwise, you will get a TypeScript error and some variants will not have proper colors. If you only have one color value, you can either pick the remaining colors manually or use the colors generator tool.

You can add more than 10 shades per color: these values will not be used by Mantine components with the default colors resolver, but you can still reference them by index, for example, color="blue.11".

Neutral color

Use color="neutral" for black in light mode and white in dark mode. Hover styles and light backgrounds adjust automatically, while the white variant keeps black text on its white background:

import { Button, Group } from '@mantine/core';

function Demo() {
  return (
    <Group>
      <Button color="neutral" variant="filled">Filled</Button>
      <Button color="neutral" variant="light">Light</Button>
      <Button color="neutral" variant="outline">Outline</Button>
      <Button color="neutral" variant="subtle">Subtle</Button>
      <Button color="neutral" variant="transparent">Transparent</Button>
      <Button color="neutral" variant="white">White</Button>
    </Group>
  );
}

Unlike regular palettes, neutral shades share one scheme-aware value. Set neutral as the primary color to use it throughout your app:

import { createTheme, MantineProvider } from '@mantine/core';

const theme = createTheme({
  primaryColor: 'neutral',
});

function Demo() {
  return <MantineProvider theme={theme}>{/* Your app */}</MantineProvider>;
}

Use --mantine-color-neutral-filled for this color in CSS. Numbered --mantine-color-neutral-0..9 variables belong to the neutral scale instead.

Virtual colors

A virtual color is a special color whose values should be different for light and dark color schemes. To define a virtual color, use the virtualColor function which accepts an object with the following properties as a single argument:

  • name – color name, must be the same as the key in theme.colors object
  • light – a key of theme.colors object for light color scheme
  • dark – a key of theme.colors object for dark color scheme

To see the demo in action, switch between light and dark color schemes (Ctrl + J):

This box has virtual background color, it is pink in dark mode and cyan in light mode
import { createTheme, MantineProvider, virtualColor } from '@mantine/core';
import { Demo } from './Demo';

const theme = createTheme({
  colors: {
    primary: virtualColor({
      name: 'primary',
      dark: 'pink',
      light: 'cyan',
    }),
  },
});

function App() {
  return (
    <MantineProvider theme={theme}>
      <Demo />
    </MantineProvider>
  );
}

colorsTuple

Use the colorsTuple function to:

  • Use a single color as the same color for all shades
  • Transform dynamic string arrays to Mantine color tuple (the array should still have 10 values)
import { colorsTuple, createTheme } from '@mantine/core';

const theme = createTheme({
  colors: {
    custom: colorsTuple('#FFC0CB'),
    dynamic: colorsTuple(
      Array.from({ length: 10 }, (_, index) => '#FFC0CB')
    ),
  },
});

Supported color formats

You can use the following color formats in theme.colors:

  • HEX: #fff, #ffffff
  • RGB: rgb(255, 255, 255), rgba(255, 255, 255, 0.5)
  • HSL: hsl(0, 0%, 100%), hsla(0, 0%, 100%, 0.5)
  • OKLCH: oklch(96.27% 0.0217 238.66), oklch(96.27% 0.0217 238.66 / 0.5)

Example of adding an oklch color to theme:

import { MantineProvider, createTheme, Group, Button } from '@mantine/core';

const theme = createTheme({
  colors: {
    'oklch-blue': [
      'oklch(96.27% 0.0217 238.66)',
      'oklch(92.66% 0.0429 240.01)',
      'oklch(86.02% 0.0827 241.66)',
      'oklch(78.2% 0.13 243.83)',
      'oklch(71.8% 0.1686 246.06)',
      'oklch(66.89% 0.1986 248.32)',
      'oklch(62.59% 0.2247 250.29)',
      'oklch(58.56% 0.2209 251.26)',
      'oklch(54.26% 0.2067 251.67)',
      'oklch(49.72% 0.1888 251.59)',
    ],
  }
});

function Demo() {
  return (
    <MantineProvider theme={theme}>
      <Group>
        <Button color="oklch-blue">Filled</Button>
        <Button color="oklch-blue" variant="outline">
          Outline
        </Button>
        <Button color="oklch-blue" variant="light">
          Light
        </Button>
      </Group>
    </MantineProvider>
  );
}

primaryColor

theme.primaryColor is a key of theme.colors, it is used:

  • As a default value for most of the components that support color prop
  • To set default focus ring outline color
import { Group, Button, MantineProvider, createTheme } from '@mantine/core';

const theme = createTheme({
  primaryColor: 'bright-pink',
  colors: {
    'bright-pink': ['#F0BBDD', '#ED9BCF', '#EC7CC3', '#ED5DB8', '#F13EAF', '#F71FA7', '#FF00A1', '#E00890', '#C50E82', '#AD1374'],
  },
});

function Demo() {
  return (
    <MantineProvider theme={theme}>
      <Group>
        <Button>Primary button</Button>
        <Button color="blue">Blue button</Button>
      </Group>
    </MantineProvider>
  );
}

CSS color values at theme.primaryColor

The value of theme.primaryColor must be a key of the theme.colors object. For example, blue, orange, or green. You cannot assign CSS color values; for example, the following code will throw an error during theme merging:

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

function Demo() {
  return (
    <MantineProvider
      theme={{
        primaryColor: '#CEFEDC', // This will throw an error
      }}
    >
      {/* Your app here */}
    </MantineProvider>
  );
}

primaryShade

theme.primaryShade is a number from 0 to 9. It determines which shade will be used for components that have a color prop.

Primary shade
import { MantineProvider, Button, Group } from '@mantine/core';

function Demo() {
  return (
    <MantineProvider theme={{ primaryShade: 6 }}>
      <Group>
        <Button>Filled</Button>
        <Button variant="light">Light</Button>
        <Button variant="outline">Outline</Button>
      </Group>
    </MantineProvider>
  );
}

You can also customize primary shade for dark and light color schemes separately:

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

function Demo() {
  return (
    <MantineProvider theme={{ primaryShade: { light: 6, dark: 8 } }}>
      {/* Your app here */}
    </MantineProvider>
  );
}

Semantic color variables

In addition to the raw shade variables (--mantine-color-gray-3, etc.), Mantine v10 exposes semantic role tokens that components use internally. You can override these to theme borders, surfaces, and text uniformly:

[data-mantine-color-scheme='light'] {
  --mantine-color-border: #d0d5dd;
  --mantine-color-text-muted: #6b7280;
}

[data-mantine-color-scheme='dark'] {
  --mantine-color-border: #374151;
  --mantine-color-text-muted: #9ca3af;
}

Key role variables and their defaults:

VariableLightDark
--mantine-color-bordergray-3dark-5
--mantine-color-border-subtlegray-2dark-7
--mantine-color-border-stronggray-5dark-3
--mantine-color-border-inputgray-4dark-4
--mantine-color-dividergray-3dark-5
--mantine-color-hovergray-0dark-7
--mantine-color-hover-stronggray-1dark-6
--mantine-color-activegray-1dark-6
--mantine-color-trackgray-3dark-5
--mantine-color-text-mutedgray-6dark-2
--mantine-color-subtle-colorgray-7dark-1
--mantine-color-surface-pagewhitedark-8
--mantine-color-surface-panelwhitedark-7
--mantine-color-surface-panel-2whitedark-5
--mantine-color-surface-sunkengray-1dark-9
--mantine-color-surface-mutedgray-0dark-7
--mantine-color-surface-inputwhitedark-7
--mantine-color-focus-ringblue-6blue-5

Role variables are defined as var() references to the underlying shade variables, so overriding --mantine-color-gray-3 still cascades into --mantine-color-border. --mantine-color-body is aliased to --mantine-color-surface-page, so overriding the latter also updates the page background.

--mantine-color-focus-ring is the color of every focus ring: the .mantine-focus-auto / .mantine-focus-always outline and the focused Input border. It follows theme.primaryColor, but unlike --mantine-primary-color-filled it uses shade 5 in dark mode instead of primaryShade.dark, so the ring stays legible against dark backgrounds. Override it to restyle focus rings everywhere without touching filled buttons.

Neutral color ladder

A --mantine-color-neutral-0..9 scale backs the role and surface tokens above. The ladder is scheme-agnostic by role – index N means the same thing in both color schemes – while the underlying shade differs so contrast holds in both. Use var(--mantine-color-neutral-N) in custom CSS when you need a neutral shade that adapts to the color scheme without hardcoding separate gray-N/dark-N pairs:

VariableRoleLightDark
--mantine-color-neutral-0Pagewhitedark-8
--mantine-color-neutral-1Panelwhitedark-7
--mantine-color-neutral-2Hover / raisedgray-0dark-6
--mantine-color-neutral-3Activegray-2dark-5
--mantine-color-neutral-4Bordergray-3dark-4
--mantine-color-neutral-5Border strong / disabledgray-5dark-3
--mantine-color-neutral-6Dimmedgray-6dark-2
--mantine-color-neutral-7Secondary textgray-7dark-1
--mantine-color-neutral-8Textblackdark-0
--mantine-color-neutral-9Max contrastblackwhite

Mantine components consume this ladder directly for neutral surfaces that have no dedicated role token – striped table rows, filled fieldsets and accordions, chart empty cells, checkerboard overlays, drag handles and similar – so overriding --mantine-color-neutral-N re-themes them together with the role tokens. A few component styles intentionally keep scheme-specific values and are not affected by ladder overrides: code blocks rendered with a forced codeColorScheme (CodeHighlight), the inverted Tooltip and Slider label bubbles, and the accent-tinted drag-and-drop targets in @mantine/schedule.

Dark neutral flavors

Four pre-built neutral color tuples are exported for use as theme.colors.dark:

import {
  darkColors,
  darkColdColors,
  darkWarmColors,
  darkTintedColors,
  createTheme,
} from '@mantine/core';

// Use a warm-tinted dark neutral ramp
const theme = createTheme({
  colors: {
    dark: darkWarmColors,
  },
});
ExportDescription
darkColorsNeutral (near-zero chroma)
darkColdColorsSlightly cool-tinted
darkWarmColorsSlightly warm-tinted
darkTintedColorsPrimary-color hue mixed in

tintColors

Use tintColors to mix a color into every shade of a MantineColorsTuple. For example, create a custom dark palette:

import { tintColors, darkColors, createTheme } from '@mantine/core';

const theme = createTheme({
  colors: {
    dark: tintColors(darkColors, '#5c7cfa', 0.15),
  },
});

strength (default 0.1) controls how much of the tint is mixed in. Middle shades of the tuple receive proportionally more tint than the shades near either end of the ramp.

The result contains CSS color-mix() expressions, which the browser resolves when applying styles.

Neutral shades tint

Override theme.colors.gray and theme.colors.dark to reproduce the tint in this website's theme settings. Gray uses 40% of the mixing strength: 10% for dark shades corresponds to 4% for gray shades.

Install @mantine/colors-generator to use mixNeutralColors:

yarn add @mantine/colors-generator

Pass a palette, tint color and percentage to mixNeutralColors. For Mantine's default OKLCH palettes, it keeps lightness close to the original:

import { mixNeutralColors } from '@mantine/colors-generator';
import {
  createTheme,
  darkColors,
  DEFAULT_THEME,
  MantineProvider,
} from '@mantine/core';

const primaryColor = 'blue';
const strength = 8;
const tint = DEFAULT_THEME.colors[primaryColor][6];

const theme = createTheme({
  primaryColor,
  colors: {
    dark: mixNeutralColors(darkColors, tint, strength),
    gray: mixNeutralColors(DEFAULT_THEME.colors.gray, tint, strength * 0.4),
  },
});

function Demo() {
  return <MantineProvider theme={theme}>{/* Your app */}</MantineProvider>;
}

Warm and cold neutrals

Use grayWarmColors and darkWarmColors for warm neutrals in both color schemes. For cold neutrals, use grayColdColors and darkColdColors instead:

import {
  createTheme,
  darkWarmColors,
  grayWarmColors,
} from '@mantine/core';

const theme = createTheme({
  colors: {
    dark: darkWarmColors,
    gray: grayWarmColors,
  },
});

Pass warm or cold palettes to mixNeutralColors to combine both effects:

import { mixNeutralColors } from '@mantine/colors-generator';
import { createTheme, darkWarmColors, DEFAULT_THEME, grayWarmColors } from '@mantine/core';

const primaryColor = 'blue';
const strength = 8;
const tint = DEFAULT_THEME.colors[primaryColor][6];

const theme = createTheme({
  primaryColor,
  colors: {
    dark: mixNeutralColors(darkWarmColors, tint, strength),
    gray: mixNeutralColors(grayWarmColors, tint, strength * 0.4),
  },
});

Surface component

Surface is the depth-aware background primitive introduced in v10. It replaces Paper (deprecated in v10, removed in v11) and supports automatic elevation stepping in dark mode – each nested Surface renders one level above its parent by default:

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

function Demo() {
  return (
    <Surface shadow="sm" radius="md" p="md">
      <Surface p="md">
        Inner surface – one level deeper in dark mode
      </Surface>
    </Surface>
  );
}

Depth can also be set explicitly with the level prop, either as an absolute 0–2 value or as a relative string like level="+1"/level="-1" that steps from the parent surface's level. Either form overrides autoDepth and clamps to the 0–2 range. See the Surface documentation for all details.

Surface backgrounds can be overridden per color scheme with the surfaces theme key, without touching CSS variables directly:

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

const theme = createTheme({
  surfaces: {
    dark: {
      panel: '#101113',
    },
  },
});

Each scheme (light/dark) accepts page, panel, panel2, sunken, muted and input keys, matching the six surface tokens documented above.

--mantine-color-surface-input is the background of inputs, checkboxes, radios, Dropzone and RichTextEditor. It is white in light mode and dark-7 in dark mode, one shade above the page, so fields stand out from the page background.

--mantine-color-surface-muted is the background of code and inset content – Code, Kbd, CodeHighlight, JsonViewer, Typography pre/code/kbd, striped table rows and filled Fieldset and Accordion. It is one step off the page in both color schemes (gray-0 / dark-7). --mantine-color-surface-sunken stays on the well value (gray-1 / dark-9) used by the SegmentedControl root, the Tabs contained list, and ScrollArea scrollbars, where a raised indicator sits inside the well. Kbd also uses it in dark mode, so keys stay visible inside inputs.

Color prop

Components that support changing their color have color prop. This prop supports the following values:

  • Key of theme.colors, for example, blue or green
  • Key of theme.colors with color index, for example, blue.5 or green.9
  • CSS color value, for example, #fff or rgba(0, 0, 0, 0.5)

Filled variant

Light variant

Outline variant

import { Group, Button, Text } from '@mantine/core';

function Demo() {
  return (
    <>
      <Text size="sm" mb={5} fw={500}>
        Filled variant
      </Text>
      <Group>
        <Button color="cyan">Theme color</Button>
        <Button color="#1D72FE">Hex color</Button>
      </Group>

      <Text size="sm" mb={5} mt="md" fw={500}>
        Light variant
      </Text>
      <Group>
        <Button variant="light" color="cyan">
          Theme color
        </Button>
        <Button variant="light" color="#1D72FE">
          Hex color
        </Button>
      </Group>

      <Text size="sm" mb={5} mt="md" fw={500}>
        Outline variant
      </Text>
      <Group>
        <Button variant="outline" color="cyan">
          Theme color
        </Button>
        <Button variant="outline" color="#1D72FE">
          Hex color
        </Button>
      </Group>
    </>
  );
}

Colors index reference

You can reference colors by index in the color prop and style props, for example the c prop:

Text with blue.6 color

Index
import { Button, Text } from '@mantine/core';

function Demo() {
  return (
    <>
      <Text c="blue.6">Text with blue.6 color</Text>
      <Button color="cyan.6">Button</Button>
    </>
  );
}

Difference between color and c props

The color prop is used to control multiple CSS properties of the component. These properties can vary across different components, but usually the color prop controls background, color, and border-color CSS properties. For example, when you set color="#C3FF36" on the Button component (with variant="filled"), it will set the following CSS properties:

  • background-color to #C3FF36
  • background-color when the button is hovered to #B0E631 (#C3FF36 darkened by 10%)
  • color to var(--mantine-color-white)
  • border-color to transparent

c is a style prop – it is responsible for setting a single CSS property color (color of the text). You can combine both props to achieve better contrast between text and background. In the following example:

  • The color prop sets background: #C3FF36 and color: var(--mantine-color-white)
  • The c prop overrides color styles to color: var(--mantine-color-black)
import { Button } from '@mantine/core';

function Demo() {
  return (
    <Button color="#C3FF36" c="black">
      Button with color and c props
    </Button>
  );
}

Colors variant resolver

theme.variantColorResolver is a function that is used to determine which colors will be used in different variants in the following components: Alert, Avatar, Button, Badge, and ActionIcon.

It accepts an object argument with the following properties:

interface VariantColorsResolverInput {
  /** `color` prop passed to component */
  color: MantineColor | undefined;

  /** `variant` prop passed to component */
  variant: string;

  /** `gradient` prop passed to component, used only for gradient variant by default */
  gradient?: MantineGradient;

  /** Theme object */
  theme: MantineTheme;
}

theme.variantColorResolver must return an object with the following properties:

interface VariantColorResolverResult {
  background: string;
  hover: string;
  color: string;
  border: string;
}

You can use theme.variantColorResolver to customize colors handling by default variants or to add support for new variants:

import {
  Button,
  Group,
  MantineProvider,
  defaultVariantColorsResolver,
  VariantColorsResolver,
  parseThemeColor,
  rgba,
  darken,
} from '@mantine/core';

const variantColorResolver: VariantColorsResolver = (input) => {
  const defaultResolvedColors = defaultVariantColorsResolver(input);
  const parsedColor = parseThemeColor({
    color: input.color || input.theme.primaryColor,
    theme: input.theme,
  });

  // Override some properties for variant
  if (parsedColor.isThemeColor && parsedColor.color === 'lime' && input.variant === 'filled') {
    return {
      ...defaultResolvedColors,
      color: 'var(--mantine-color-black)',
      hoverColor: 'var(--mantine-color-black)',
    };
  }

  // Completely override variant
  if (input.variant === 'light') {
    return {
      background: rgba(parsedColor.value, 0.1),
      hover: rgba(parsedColor.value, 0.15),
      border: `1px solid ${parsedColor.value}`,
      color: darken(parsedColor.value, 0.1),
    };
  }

  // Add new variants support
  if (input.variant === 'danger') {
    return {
      background: 'var(--mantine-color-red-8)',
      hover: 'var(--mantine-color-red-9)',
      color: 'var(--mantine-color-white)',
      border: 'none',
    };
  }

  return defaultResolvedColors;
};

function Demo() {
  return (
    <MantineProvider theme={{ variantColorResolver }}>
      <Group>
        <Button color="lime.4" variant="filled">
          Lime filled button
        </Button>

        <Button color="orange" variant="light">
          Orange light button
        </Button>

        <Button variant="danger">Danger button</Button>
      </Group>
    </MantineProvider>
  );
}

Colors generation

Use the colors generator to generate 10 shades from a single color. To generate colors at runtime, install the @mantine/colors-generator package:

yarn add @mantine/colors-generator

generateColors accepts any CSS color and returns a MantineColorsTuple of 10 OKLCH shades. The input color is kept as is at the shade that matches its lightness, the other shades are built around it:

import { generateColors } from '@mantine/colors-generator';
import { MantineProvider } from '@mantine/core';

function Demo() {
  return (
    <MantineProvider
      theme={{
        colors: {
          brand: generateColors('#375EAC'),
        },
      }}
    >
      {/* Your app here */}
    </MantineProvider>
  );
}

The second argument adjusts the generated shades. All options are optional:

import { generateColors } from '@mantine/colors-generator';

const yellow = generateColors('#fcc419', {
  // Shade that is set to the input color, 0-9, 'auto' by default
  baseShade: 6,
  // Lightness of shades 0 and 9, 0-1
  lightest: 0.97,
  darkest: 0.4,
  // Saturation of shades 0 and 9 relative to the input color, 0-1
  lightestChroma: 0.1,
  darkestChroma: 0.8,
  // Hue rotation in degrees from shade 0 to shade 9
  hueShift: -25,
});

generateColorFormats returns the palette in oklch, hex, rgb and hsl formats together with the index of the base shade:

import { generateColorFormats } from '@mantine/colors-generator';

const result = generateColorFormats('#375EAC', { baseShade: 7 });
// result.colors       – MantineColorsTuple (oklch strings)
// result.formats.hex  – string[]
// result.formats.rgb  – string[]
// result.baseColorIndex – 7

Default colors

Add custom colors types

TypeScript will only autocomplete Mantine's default colors when accessing the theme. To add your custom colors to the MantineColor type, you can use TypeScript module declaration.

import {
  DefaultMantineColor,
  MantineColorsTuple,
} from '@mantine/core';

type ExtendedCustomColors =
  | 'primaryColorName'
  | 'secondaryColorName'
  | DefaultMantineColor;

declare module '@mantine/core' {
  export interface MantineThemeColorsOverride {
    colors: Record<ExtendedCustomColors, MantineColorsTuple>;
  }
}