Castle UI now converts theme tokens (colors, font sizes, stc) to CSS Custom Properties (also known as "CSS variables").

CSS variables are now supported in all modern browsers, and we think they are useful to:

• avoid prop interpolations;
• avoid classname regeneration from emotion;
• reduce runtime evaluation of token values in Theme context;
• use theme token outside Chakra's component (embedded forms, markdown content, etc.)

Overview

There are three main components you should know about when using CSS variables:

• How Chakra converts tokens to custom properties
• How to consume them in and outside Chakra's component
• Where we attach the custom properties to

Converting theme tokens to CSS variables

By default, Castle UI converts theme tokens defined in your theme (or our default theme) to CSS variables internally so you don't have to.

Given a theme object that looks like this:

const theme = {
  fontSizes: {
    lg: '18px',
  },
  colors: {
    gray: {
      100: '#fafafa',
      200: '#f7f7f7',
    },
  },
}
content_copy
Copy

When you pass this theme to the ChakraProvider, we'll automatically generate CSS variables that look like:

:root {
  --chakra-fontSizes-lg: '18px';
  --chakra-colors-gray-100: '#fafafa';
  --chakra-colors-gray-200: '#f7f7f7';
}
content_copy
Copy

Note: The generated custom properties are prefixed with chakra-* to avoid conflicts with third party CSS.

Consuming CSS Variables

When using Chakra's components, we manage the conversion of theme tokens to their respective css variable.

// You type this
<Box color="gray.100" />

// Chakra generates something like
.css-box {
   color: "var(--chakra-colors-gray-100)"
}
content_copy
Copy

Note: We do this automatically when you pass style props or use the sx prop.

Styling non-chakra components

In certain scenarios, you might need to style components that are not managed by Chakra. In this case, you can use the raw CSS variable values.

// let's say you have an embedded form
<FormiumForm />
content_copy
Copy

You can write custom CSS to style the components

.formium-form {
  color: var(--chakra-colors-gray-700);
  background-color: var(--chakra-colors-gray-50);
}
content_copy
Copy

or wrap the component in <Box/> and style it with convenience.

<Box sx={{ '.formium': { bg: 'gray.50', color: 'gray.700' } }}>
  <FormiumForm />
</Box>
content_copy
Copy

Attaching the CSS variables

By default, Chakra attaches the generated CSS variables to the :root element.

The :root pseudo-class represents the top level of the HTML document.

To change the root element that Chakra attaches the CSS variables to, pass the cssVarsRoot prop to ChakraProvider and set its value to the css selector of the element you want.

<ChakraProvider cssVarsRoot="#app">
  <App />
</ChakraProvider>
content_copy
Copy

Creating scoped, theme-aware CSS variables

This is experimental and might be removed in future versions

When using the sx prop or the chakra(...) factory, you can create variables that reference theme tokens. This makes it possible to change property values based on breakpoint, or light/dark mode with ease.

<Box
  sx={{
    // "colors.gray.100" is shorthand for 'var(--chakra-colors-gray.100)'
    '--banner-color': 'colors.gray.100',
    '.external-banner': {
      bg: 'var(--banner-color)',
      '.button': {
        borderColor: 'var(--banner-color)',
      },
    },
  }}
>
  <ExternalBanner />
</Box>
content_copy
Copy