Why is it required to have 10 shades per color?

How Mantine colors are defined and used

New colors are added to the theme.colors object. Each color must have 10 shades from lightest to darkest. Colors specified in theme.colors are available in all components that support color prop.

theme.primaryColor determines which color from theme.colors is used as default color in most components that support color prop.

theme.primaryShade determines which shade from theme.colors[color] is used as default color in components with filled variant.

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

const theme = createTheme({
  colors: {
    oceanBlue: [
      '#7AD1DD', // lightest
      '#5FCCDB',
      '#44CADC',
      '#2AC9DE',
      '#1AC2D9',
      '#11B7CD',
      '#09ADC3', // primaryShade light
      '#0E99AC',
      '#128797', // primaryShade dark
      '#147885', // darkest
    ],
  },

  // theme.primaryColor must be key of theme.colors object,
  // hex/rgb/other values are not supported
  primaryColor: 'oceanBlue',

  // primaryShade is the index of main color in theme.colors[color] arrays
  // theme.colors[color][primaryShade] is used in components with filled variant
  primaryShade: { light: 6, dark: 8 },
});

Why is it required to have 10 shades per color?

Mantine components have different variants and support light and dark color schemes. Having 10 shades per color allows maintaining consistent colors with proper contrast and brightness levels across all variants and color schemes.

For example, Button component has filled and light variants which use different shades of theme.colors depending on color scheme:

In the above example:

• Filled button:
  • background in light color scheme: blue[6]
  • hover background in light color scheme: blue[7]
  • background in dark color scheme: blue[8]
  • hover background in dark color scheme: blue[9]
• Light button:
  • background in light color scheme: blue[0]
  • hover background in light color scheme: blue[1]
  • text color in light color scheme: blue[6]
  • background in dark color scheme: color-mix(in srgb, blue[6], transparent 12%)
  • hover background in dark color scheme: color-mix(in srgb, blue[6], transparent 15%)
  • text color in dark color scheme: blue[4]

Can I have just one shade per color?

If you do not plan to use light variant, support different colors for light/dark color schemes, and you do not rely on color changes for hover effects, you can define just one shade per color with colorsTuple function:

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

const theme = createTheme({
  colors: {
    custom: colorsTuple('#FFC0CB'),
  },
});

Can I have more that 10 shades per color?

Yes, it is possible to define more than 10 shades per color, but Mantine components will use only the first 10 of them. Other colors values will be available in theme.colors object and as CSS variables, for example var(--mantine-color-blue-11).