css

The css function is the core styling utility in Theme UI. It processes style objects, performs theme lookups, handles responsive arrays, and transforms shorthand properties into their full CSS equivalents.

Function Signature

function css<TTheme extends Theme>(
  args: ThemeUIStyleObject<TTheme> = {}
): (props: { theme: Theme } | Theme) => CSSObject

Parameters

ThemeUIStyleObject<TTheme>

Style object containing CSS properties, aliases, and theme-aware values. Can be:

Plain style object with CSS properties
Function that receives the theme and returns a style object
Object with responsive arrays for mobile-first styling
Object with variant references

Returns

(props) => CSSObject

Returns a function that accepts a theme object (or { theme } prop object) and returns the final CSS object with all transformations applied.

How It Works

1. Theme Lookups

The css function automatically looks up values from theme scales based on the CSS property:

import { css } from '@theme-ui/css'

const theme = {
  colors: {
    primary: '#07c',
    secondary: '#639'
  },
  space: [0, 4, 8, 16, 32]
}

const styles = css({
  color: 'primary',      // → '#07c'
  padding: 3,            // → 16
  margin: 2              // → 8
})(theme)

2. Responsive Arrays

Arrays are transformed into mobile-first media queries using the theme’s breakpoints:

const styles = css({
  fontSize: [1, 2, 3],
  padding: [2, 3, 4]
})(theme)

// Transforms to:
// {
//   fontSize: theme.fontSizes[1],
//   '@media screen and (min-width: 40em)': { fontSize: theme.fontSizes[2] },
//   '@media screen and (min-width: 52em)': { fontSize: theme.fontSizes[3] }
// }

3. Property Aliases

Shorthand properties are expanded to their full CSS equivalents:

const styles = css({
  bg: 'primary',    // → backgroundColor: theme.colors.primary
  m: 2,             // → margin: theme.space[2]
  px: 3,            // → paddingLeft + paddingRight: theme.space[3]
  py: 2             // → paddingTop + paddingBottom: theme.space[2]
})(theme)

Available Aliases

bg → backgroundColor
m → margin
mt → marginTop
mr → marginRight
mb → marginBottom
ml → marginLeft
mx → marginX (expands to left + right)
my → marginY (expands to top + bottom)
p → padding
pt → paddingTop
pr → paddingRight
pb → paddingBottom
pl → paddingLeft
px → paddingX (expands to left + right)
py → paddingY (expands to top + bottom)

4. Multiple Properties

Some properties expand to multiple CSS properties:

const styles = css({
  marginX: 2,    // → marginLeft: 8, marginRight: 8
  paddingY: 3,   // → paddingTop: 16, paddingBottom: 16
  size: 100      // → width: 100, height: 100
})(theme)

Available Multiples

marginX → marginLeft, marginRight
marginY → marginTop, marginBottom
paddingX → paddingLeft, paddingRight
paddingY → paddingTop, paddingBottom
scrollMarginX → scrollMarginLeft, scrollMarginRight
scrollMarginY → scrollMarginTop, scrollMarginBottom
scrollPaddingX → scrollPaddingLeft, scrollPaddingRight
scrollPaddingY → scrollPaddingTop, scrollPaddingBottom
size → width, height

5. Negative Values

Certain properties (margins, positioning) support negative values:

const styles = css({
  marginTop: -2,        // → -8 (negates theme.space[2])
  marginLeft: '-2',     // → -8 (string form)
  top: -1               // → -4
})(theme)

6. Nested Scales with `__default`

Theme scales can be nested with a __default key:

const theme = {
  colors: {
    primary: {
      __default: '#07c',
      light: '#39f',
      dark: '#05a'
    }
  }
}

const styles = css({
  color: 'primary',        // → '#07c' (uses __default)
  bg: 'primary.light'      // → '#39f'
})(theme)

7. Variant References

Reference predefined variants from the theme:

const theme = {
  buttons: {
    primary: {
      color: 'white',
      bg: 'primary',
      padding: 3,
      borderRadius: 2
    }
  }
}

const styles = css({
  variant: 'buttons.primary',
  fontSize: 2  // Additional styles merged with variant
})(theme)

Theme Scale Mappings

The css function maps CSS properties to theme scales automatically:

Colors

Maps to theme.colors:

color
backgroundColor, background
borderColor, borderTopColor, borderBottomColor, borderLeftColor, borderRightColor
borderBlockColor, borderBlockEndColor, borderBlockStartColor
borderInlineColor, borderInlineEndColor, borderInlineStartColor
caretColor
columnRuleColor
outlineColor
textDecorationColor
accentColor
fill, stroke (SVG)

Space

Maps to theme.space:

margin, marginTop, marginRight, marginBottom, marginLeft
marginX, marginY
marginBlock, marginBlockEnd, marginBlockStart
marginInline, marginInlineEnd, marginInlineStart
padding, paddingTop, paddingRight, paddingBottom, paddingLeft
paddingX, paddingY
paddingBlock, paddingBlockEnd, paddingBlockStart
paddingInline, paddingInlineEnd, paddingInlineStart
top, right, bottom, left
inset, insetBlock, insetBlockEnd, insetBlockStart
insetInline, insetInlineEnd, insetInlineStart
scrollMargin, scrollMarginTop, scrollMarginRight, scrollMarginBottom, scrollMarginLeft
scrollMarginX, scrollMarginY
scrollPadding, scrollPaddingTop, scrollPaddingRight, scrollPaddingBottom, scrollPaddingLeft
scrollPaddingX, scrollPaddingY
gap, gridGap, columnGap, gridColumnGap, rowGap, gridRowGap

Typography

fontFamily → theme.fonts
fontSize → theme.fontSizes
fontWeight → theme.fontWeights
lineHeight → theme.lineHeights
letterSpacing → theme.letterSpacings

Borders

border, borderTop, borderRight, borderBottom, borderLeft → theme.borders
borderBlock, borderBlockEnd, borderBlockStart → theme.borders
borderInline, borderInlineEnd, borderInlineStart → theme.borders
borderWidth, borderTopWidth, borderBottomWidth, borderLeftWidth, borderRightWidth → theme.borderWidths
borderBlockWidth, borderBlockEndWidth, borderBlockStartWidth → theme.borderWidths
borderInlineWidth, borderInlineEndWidth, borderInlineStartWidth → theme.borderWidths
borderStyle, borderTopStyle, borderBottomStyle, borderLeftStyle, borderRightStyle → theme.borderStyles
borderBlockStyle, borderBlockEndStyle, borderBlockStartStyle → theme.borderStyles
borderInlineStyle, borderInlineEndStyle, borderInlineStartStyle → theme.borderStyles
columnRuleWidth → theme.borderWidths

Radii

Maps to theme.radii:

borderRadius
borderTopLeftRadius, borderTopRightRadius
borderBottomLeftRadius, borderBottomRightRadius
borderEndEndRadius, borderEndStartRadius
borderStartEndRadius, borderStartStartRadius

Sizes

Maps to theme.sizes:

width, minWidth, maxWidth
height, minHeight, maxHeight
flexBasis
size
blockSize, minBlockSize, maxBlockSize
inlineSize, minInlineSize, maxInlineSize
columnWidth

Other Scales

boxShadow, textShadow → theme.shadows
zIndex → theme.zIndices
opacity → theme.opacities
transition → theme.transitions

Default Theme

If no theme is provided, css uses these defaults:

{
  space: [0, 4, 8, 16, 32, 64, 128, 256, 512],
  fontSizes: [12, 14, 16, 20, 24, 32, 48, 64, 72]
}

Default Breakpoints

When no breakpoints are defined in the theme:

['40em', '52em', '64em']

Examples

Basic Usage

import { css } from '@theme-ui/css'

const styles = css({
  color: 'primary',
  bg: 'background',
  padding: 3,
  fontSize: 2
})

const element = <div css={styles(theme)} />

Responsive Styles

const styles = css({
  fontSize: [1, 2, 3, 4],
  padding: [2, 3, 4],
  width: ['100%', '80%', '60%', '50%']
})

Nested Styles

const styles = css({
  color: 'text',
  ':hover': {
    color: 'primary'
  },
  '& > a': {
    textDecoration: 'none'
  }
})

Function Form

const styles = css((theme) => ({
  color: theme.colors.primary,
  fontSize: theme.fontSizes[2],
  padding: theme.space[3]
}))

get - Extract values from theme objects
sx prop - Component-level styling with the sx prop

Core

Styling

Color Modes

Components

Packages

css

css

Function Signature

Parameters

Returns

How It Works

1. Theme Lookups

2. Responsive Arrays

3. Property Aliases

Available Aliases

4. Multiple Properties

Available Multiples

5. Negative Values

6. Nested Scales with `__default`

7. Variant References

Theme Scale Mappings

Default Theme

Default Breakpoints

Examples

Basic Usage

Responsive Styles

Nested Styles

Function Form

​css

​Function Signature

​Parameters

​Returns

​How It Works

​1. Theme Lookups

​2. Responsive Arrays

​3. Property Aliases

​Available Aliases

​4. Multiple Properties

​Available Multiples

​5. Negative Values

​6. Nested Scales with __default

​7. Variant References

​Theme Scale Mappings

​Default Theme

​Default Breakpoints

​Examples

​Basic Usage

​Responsive Styles

​Nested Styles

​Function Form

​Related

css

Function Signature

Parameters

Returns

How It Works

1. Theme Lookups

2. Responsive Arrays

3. Property Aliases

Available Aliases

4. Multiple Properties

Available Multiples

5. Negative Values

6. Nested Scales with `__default`

7. Variant References

Theme Scale Mappings

Default Theme

Default Breakpoints

Examples

Basic Usage

Responsive Styles

Nested Styles

Function Form

Related