Skip to content
Theme UI
GitHub

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.

PropertyTheme Key
fontFamilyfonts
fontSizefontSizes
fontWeightfontWeights
lineHeightlineHeights
letterSpacingletterSpacings
colorcolors
backgroundColor, bgcolors
margin, mspace
marginTop, mtspace
marginRight, mrspace
marginBottom, mbspace
marginLeft, mlspace
marginX, mxspace
marginY, myspace
padding, pspace
paddingTop, ptspace
paddingRight, prspace
paddingBottom, pbspace
paddingLeft, plspace
paddingX, pxspace
paddingY, pyspace
topspace
bottomspace
leftspace
rightspace
borderborders
borderTopborders
borderRightborders
borderBottomborders
borderLeftborders
borderColorcolors
borderWidthborderWidths
borderStyleborderStyles
borderRadiusradii
boxShadowshadows
textShadowshadows
zIndexzIndices
widthsizes
minWidthsizes
maxWidthsizes
heightsizes
minHeightsizes
maxHeightsizes
sizesizes

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
}}
/>

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>
Edit the page on GitHub
Previous:
Theming
Next:
Styling MDX