The sx Prop

The sx prop lets you style elements inline, using values from your theme. To use the sx prop, add the custom /** @jsx jsx */ pragma comment to the top of your module and import the jsx function.

/** @jsx jsx */
import { jsx } from 'theme-ui'
export default props => (
  <div
    {...props}
    sx={{
      // values referencing scales defined in a theme
      color: 'primary',
      bg: 'lightgray',
      fontFamily: 'body',
      // raw CSS value
      boxShadow: '0 0 1px 3px rgba(0, 0, 0, .125)',
    }}
  />
)

Theme-Aware Properties

The following CSS properties will use values defined in the theme, when available.

Responsive Values

Theme UI, like Styled System, includes a shorthand syntax for writing mobile-first responsive styles using arrays as values. This is useful when you want to change a single property across multiple breakpoints without needing to write verbose media query syntax.

/** @jsx jsx */
import { jsx } from 'theme-ui'
export default props => (
  <div
    {...props}
    sx={{
      width: ['100%', '50%', '25%'],
    }}
  />
)

Skipping Breakpoints

If you want to skip a breakpoint, you can use the value null. This is useful if you want to set a value for only the largest breakpoint, for example.

/** @jsx jsx */
import { jsx } from 'theme-ui'
export default props => (
  <div
    {...props}
    sx={{
      width: [null, null, '25%'],
    }}
  />
)

Margin and Padding

Margin and padding are treated as first-class citizens in Theme UI, using values defined in the theme.space scale, and include an optional shorthand syntax for using negative space in your application.

In addition to shorthands for applying margin and padding on the x- and y-axes, a terse naming convention can be used to quickly edit styles.

// example of using margin and padding shorthand syntax
<div
  sx={{
    px: 3, // padding-left & padding-right
    // paddingX: 3 will also work
    py: 4, // padding-top & padding-bottom
    mb: 3, // margin-bottom
  }}
/>

Composition

Styles can be composed by using an array of style objects in the sx prop. This works the same way as Emotion.

import React from 'react'
import { css } from 'theme-ui'
const base {
  backgroundColor: 'background',
  color: 'primary'
}
const danger = {
  color: 'red'
}
export default props => (
  <div>
    <div sx={base}>This will be the primary color</div>
    <div sx={[danger, base]}>
      This will be also be primary since the base styles
      overwrite the danger styles.
    </div>
    <div sx={[base, danger]}>This will be red</div>
  </div>
)

Functional Values

For shorthand CSS properties or ones that are not automatically mapped to values in the theme, use an inline function to reference values from the theme object.

/** @jsx jsx */
import { jsx } from 'theme-ui'
export default props => (
  <div
    {...props}
    sx={{
      boxShadow: theme => `0 0 4px ${theme.colors.primary}`,
    }}
  />
)

Child Selectors

In some cases you might want to apply styles to children of the current element. You can do so with Emotion's nested selectors.

If you want to reference the current class of the component, you can use the & symbol.

/** @jsx jsx */
import { jsx } from 'theme-ui'
export default props => (
  <div
    {...props}
    sx={{
      h1: {
        backgroundColor: 'tomato'
      },
      '& > div': {
        fontSize: [2, 3, 4]
      }
    }}
  />
)

Raw CSS

To opt-out of using theme-based CSS, use the css prop to render raw CSS values.

/** @jsx jsx */
import { jsx } from 'theme-ui'
export default props => (
  <div
    {...props}
    css={{
      // raw values
      color: 'tomato',
      fontSize: 24,
    }}
  />
)

Using the sx Prop in MDX

Because MDX uses its own custom pragma and createElement function, the Theme UI pragma will not work in MDX files. You can use any of the Theme UI components, which support the sx prop, in an MDX file as a workaround.

<!-- Example -->
import { Box } from 'theme-ui'
<Box
  sx={{
    padding: 3,
    bg: 'highlight',
  }}>
# Hello
</Box>