Virtual Color

Create color placeholders for better theming and customization.

Overview

Cerberus allows you to create a virtual color or color placeholder in your project. The colorPalette property is how you create virtual color.

1
<Box
2
  colorPalette="action"
3
  bgColor={{
4
    base: "colorPalette.bg.initial",
5
    _hover: "colorPalette.bg.hover"
6
  }}
7
>
8
  Hello World
9
</Box>

This will translate to the action.bg.initial background color and action.bg.hover background color on hover.

The fundamental requirement for virtual colors is that your colors must have a consistent naming convention. By default, Cerberus uses our Semantic Palettes for each color we provide which corresponds to how it should be used in your application.

This makes it easier for you to create and use virtual colors based on theming. Let's say we need to create a themable outline button from scratch.

1
<Button
2
  css={{
3
    colorPalette: 'action',
4
    borderWidth: '1px',
5
    borderColor: 'colorPalette.border.initial',
6
    color: 'colorPalette.text.initial',
7
    _hover: {
8
      borderColor: 'colorPalette.border.100',
9
    }
10
    _focus: {
11
      borderColor: 'colorPalette.border.focus',
12
    }
13
  }}
14
>
15
  Click me
16
</Button>

Recipes

Virtual colors are most useful when used with recipes.

1
const buttonRecipe = defineRecipe({
2
  base: {
3
    alignItems: "center",
4
    bg: "colorPalette.bg.initial",
5
    color: "colorPalette.text.initial",
6
    display: "flex",
7
    justifyContent: "center",
8
    _hover: {
9
      bg: "colorPalette.bg.hover",
10
    },
11
  },
12
  variants: {
13
    palette: {
14
      action: {
15
        colorPalette: "action",
16
      },
17
      secondary: {
18
        colorPalette: "secondaryAction",
19
      },
20
    },
21
  },
22
})

Components

Most built-in components in Cerberus support virtual colors via the palette prop. To override the palette with a custom palette in your theme, use the css prop to define the virtual color.

1
<Button
2
  css={{
3
    colorPalette: 'myCustomActionPalette',
4
  }}
5
>
6
  Click me
7
</Button>

Dark mode

Another amazing thing you can do with virtual colors is to use them with dark mode.

1
<Box
2
  colorPalette="page"
3
  bg={{
4
     base: "colorPalette.surface.initial",
5
     _dark: "colorPalette.surface.inverse"
6
 }}
7
>
8
  Hello World
9
</Box>

This element will have a page.surface.initial background color in light mode and a page.surface.inverse background color in dark mode.

On this page