@theme-ui/css

The @theme-ui/css package contains the framework-agnostic core logic of Theme UI. It provides the css function and TypeScript types for writing style objects with responsive, theme-aware ergonomic shortcuts.

Installation

npm install @theme-ui/css @emotion/react

When to Use

Use @theme-ui/css when you:

Want to use Theme UI’s styling logic without React
Need framework-agnostic styling utilities
Are integrating with other libraries or frameworks
Want to use the css function in vanilla JavaScript
Need TypeScript types for Theme UI themes

If you’re using the umbrella theme-ui package or @theme-ui/core, this package is already included.

Exports

Functions

`css`

Transforms a Theme UI style object into a standard CSS object, resolving theme values and responsive arrays.

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

const theme = {
  colors: {
    text: '#222',
    primary: '#33e',
  },
  space: [0, 4, 8, 16, 32],
  fontSizes: [12, 14, 16, 20, 24],
}

const styles = css({
  color: 'primary',
  padding: 3, // Uses theme.space[3] = 16
  fontSize: [1, 2, 3], // Responsive: 14px, 16px, 20px
  '&:hover': {
    color: 'text',
  },
})(theme)

Signature:

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

Features:

Theme value lookup from scales (colors, space, fontSizes, etc.)
Responsive array values mapped to breakpoints
Shorthand property aliases (e.g., px, py, bg)
Nested styles and pseudo-selectors
Variant references

`get`

Extracts a value from a deeply nested object using a dot-notation path.

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

const theme = {
  colors: {
    primary: { __default: '#33e', light: '#66f' }
  }
}

get(theme, 'colors.primary') // '#33e'
get(theme, 'colors.primary.light') // '#66f'
get(theme, 'colors.notFound', 'fallback') // 'fallback'

Signature:

get(
  obj: object,
  path: string | number | undefined,
  fallback?: unknown
): any

Constants

`THEME_UI_DEFAULT_KEY`

The key used for default values in nested scales.

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

const theme = {
  colors: {
    primary: {
      [THEME_UI_DEFAULT_KEY]: '#33e',
      light: '#66f',
      dark: '#00a'
    }
  }
}

`defaultBreakpoints`

Default breakpoint values used when no breakpoints are defined in the theme.

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

console.log(defaultBreakpoints) // ['40em', '52em', '64em']

`scales`

Mapping of CSS properties to their corresponding theme scale.

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

console.log(scales.color) // 'colors'
console.log(scales.padding) // 'space'
console.log(scales.fontSize) // 'fontSizes'

`aliases`

Shorthand property aliases.

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

// Aliases include:
// bg -> backgroundColor
// m -> margin
// mt -> marginTop
// mr -> marginRight
// mb -> marginBottom
// ml -> marginLeft
// mx -> marginX
// my -> marginY
// p -> padding
// pt -> paddingTop
// pr -> paddingRight
// pb -> paddingBottom
// pl -> paddingLeft
// px -> paddingX
// py -> paddingY

`multiples`

Properties that map to multiple CSS properties.

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

// Examples:
// marginX -> ['marginLeft', 'marginRight']
// marginY -> ['marginTop', 'marginBottom']
// paddingX -> ['paddingLeft', 'paddingRight']
// paddingY -> ['paddingTop', 'paddingBottom']
// size -> ['width', 'height']

TypeScript Types

The package exports comprehensive TypeScript types:

import type {
  // Core Types
  Theme,
  ThemeUIStyleObject,
  ThemeUICSSObject,
  CSSObject,
  
  // Property Types
  CSSProperties,
  ThemeUICSSProperties,
  ThemeUIExtendedCSSProperties,
  
  // Utility Types
  ResponsiveStyleValue,
  Scale,
  StylePropertyValue,
  
  // Color Mode Types
  ColorMode,
  ColorModesScale,
  
  // Advanced Types
  CSSPseudoSelectorProps,
  CSSOthersObject,
  ThemeStyles,
  ThemeDerivedStyles,
  VariantProperty,
  Label,
  TLengthStyledSystem,
} from '@theme-ui/css'

Theme Type

The main theme interface:

interface Theme {
  // Scales
  colors?: ColorModesScale
  space?: Scale
  fontSizes?: Scale
  fonts?: Scale
  fontWeights?: Scale
  lineHeights?: Scale
  letterSpacings?: Scale
  sizes?: Scale
  borders?: Scale
  borderWidths?: Scale
  borderStyles?: Scale
  radii?: Scale
  shadows?: Scale
  zIndices?: Scale
  transitions?: Scale
  
  // Configuration
  breakpoints?: Array<string>
  config?: ThemeUIConfig
  
  // Styles
  styles?: ThemeStyles
  
  // Custom properties
  [key: string]: any
}

Entry Points

Main Entry Point

import { css, get, scales, aliases, multiples } from '@theme-ui/css'
import type { Theme, ThemeUIStyleObject } from '@theme-ui/css'

`/utils`

Utility functions for working with themes:

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

Standalone Usage

You can use @theme-ui/css without React:

import { css as transformStyleObject } from '@theme-ui/css'
import { css as createClassName } from '@emotion/css'

const theme = {
  colors: {
    text: '#222',
    primary: '#33e',
  },
  space: {
    sm: '1rem',
    md: '2rem',
  },
}

const styles = transformStyleObject({
  padding: ['sm', 'md'],
  color: 'primary',
  '&:hover': {
    color: 'text',
  },
})(theme)

const className = createClassName(styles)

Features

Responsive Values

Use arrays for responsive styles:

css({
  fontSize: [1, 2, 3, 4], // Maps to breakpoints
  padding: [2, 3, 4],
})(theme)

Negative Values

Use negative numbers or strings with - prefix:

css({
  marginTop: -3, // Negative space value
  marginLeft: '-1rem',
})(theme)

Nested Scales

Support for nested color scales with default values:

const theme = {
  colors: {
    primary: {
      __default: '#33e',
      light: '#66f',
      dark: '#00a',
    },
  },
}

css({ color: 'primary' })(theme) // Uses '#33e'
css({ color: 'primary.light' })(theme) // Uses '#66f'

Variants

Reference theme variants:

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

css({
  variant: 'buttons.primary',
  borderRadius: 4,
})(theme)

Notes

Framework-agnostic - works with or without React
No side effects - safe for tree-shaking
Requires @emotion/react as a peer dependency
Fully typed with TypeScript

@theme-ui/core - React integration
Theme Specification - Theme object structure
Responsive Styles - Working with responsive values

Core

Styling

Color Modes

Components

Packages

Installation

When to Use

Exports

Functions

`css`

`get`

Constants

`THEME_UI_DEFAULT_KEY`

`defaultBreakpoints`

`scales`

`aliases`

`multiples`

TypeScript Types

Theme Type

Entry Points

Main Entry Point

`/utils`

Standalone Usage

Features

Responsive Values

Negative Values

Nested Scales

Variants

Notes

​Installation

​When to Use

​Exports

​Functions

​css

​get

​Constants

​THEME_UI_DEFAULT_KEY

​defaultBreakpoints

​scales

​aliases

​multiples

​TypeScript Types

​Theme Type

​Entry Points

​Main Entry Point

​/utils

​Standalone Usage

​Features

​Responsive Values

​Negative Values

​Nested Scales

​Variants

​Notes

​Related

Installation

When to Use

Exports

Functions

`css`

`get`

Constants

`THEME_UI_DEFAULT_KEY`

`defaultBreakpoints`

`scales`

`aliases`

`multiples`

TypeScript Types

Theme Type

Entry Points

Main Entry Point

`/utils`

Standalone Usage

Features

Responsive Values

Negative Values

Nested Scales

Variants

Notes

Related