The css Prop

With css you can provide any valid CSS to an element and utilize tokens from your theme to ensure consistency and that you are utilizing constraint-based design principles when styling your application.

This prop provides a superset of CSS (contains all CSS properties/selectors in addition to custom ones) that maps values directly from the theme, depending on the CSS property used. Also, it allows a simple way of defining responsive values that correspond to the breakpoints defined in the theme.

To find out which properties are theme-aware, see the Style Props.

Use cases#

Although the css prop is considered an escape hatch, there are few cases where it is needed.

Defining Any Standard CSS Property#

In case you need to set a CSS property that is not listed in the Style Props list, you can use the css prop and pass it whatever CSS property you desire.

One such example is the filter property:

<Image
  src='https://images.unsplash.com/photo-1707343843344-011332037abb?w=800&auto=format&fit=crop&q=60&ixlib=rb-4.0.3&ixid=M3wxMjA3fDF8MHxlZGl0b3JpYWwtZmVlZHwxfHx8ZW58MHx8fHx8'
  alt='a kitten'
  css={{ filter: 'blur(8px)' }}
/>

Defining CSS Custom Properties#

Custom CSS properties can be defined via the css prop as well:

<Box css={{ '--my-color': '#53c8c4' }}>
  <Heading color='var(--my-color)' size='lg'>
    This uses CSS Custom Properties!
  </Heading>
</Box>

Creating Nested Selectors#

To create complex, nested selectors, you can use utilize the & operator. The & in selector will get resolved to unique className that is assigned the component you put css on.

For the following example you could also use the _groupHover shorthand prop.

<Box borderWidth={2} borderColor='purple.500' p={5} className='my-box'>
  <Heading size='lg'>
    Hover the box...
    <Box
      as='span'
      color='red.500'
      css={{
        '.my-box:hover &': {
          color: 'green.500',
        },
      }}
    >
      And I will turn green!
    </Box>
  </Heading>
</Box>

Custom Media queries#

<Box
  css={{
    '@media print': {
      display: 'none',
    },
  }}
>
  This text won't be shown when printing this page.
</Box>