API

`theme-ui`

The core theme-ui package exports the following modules.

While not being available in the theme-ui package directly, there are two separate entry points for React create element functions intended to be used in the automatic JSX runtime with a custom pragma comment. They add support for the sx prop, which uses Emotion's create element functions internally and parse style objects with the Theme UI css utility.

Usage:

/** @jsxImportSource theme-ui */

export default (props) => (
  <div
    {...props}
    sx={{
      color: 'primary',
    }}
  />
)

Imports for use without JSX:

import { jsx, jsxs } from 'theme-ui/jsx-runtime'
import { jsxDEV } from 'theme-ui/jsx-dev-runtime'

`ThemeUIProvider`

The ThemeUIProvider component is a wrapper around Emotion's ThemeUIProvider and MDX's MDXProvider. It provides default styled components to MDX content that pick up values from theme.styles. It also handles color mode state.

Prop	Type	Description
`theme`	Object	Theming context object
`components`	Object	Optional custom MDX components
`children`	Node	React children

`useThemeUI`

The useThemeUI hook returns the full Theme UI context object, which includes theme, and color mode.

const context = useThemeUI()
const { theme, components, colorMode, setColorMode } = context

`useColorMode`

The useColorMode hook returns an array with two values: the current color mode state and an updater function. The color mode state can be any string and should match the name of a color mode defined in theme.colors.modes or be a name for the default color mode.

const [colorMode, setColorMode] = useColorMode()

`BaseStyles`

The BaseStyles component can be used to style child content that isn’t generated from MDX. This can be useful with content from a CMS or Markdown.

<BaseStyles>
  <h1>
    Styled based on <code>theme.styles</code>
  </h1>
</BaseStyles>

`Context`

The React context used in Theme UI.

`css`

As an alternative to using the sx prop, the css utility is intended for use with the Emotion css prop. It will attempt to use values from the theme object for many common CSS properties, and will fall back to raw values when there is no corresponding theme value.

To see a list of supported CSS properties, see the sx prop docs.

css(styleObject)(theme)

Usage:

<div css={css(styles)} />

Argument	Type	Description
`styleObject`	Object	a theme-aware style object with support for responsive array values and Styled System prop shortcuts
`theme`	Object	the Emotion theming context object

`get`

An existential getter function used internally to extract a field (or object) from a theme object.

`getObjectWithVariants`

Similar to the get function above, but will also resolve any variant field if found inside the object.

`merge`

A function to deeply merge themes.

Usage

import dark from '@theme-ui/preset-dark'

const theme = merge(dark, {
  fontWeights: {
    body: 500,
    heading: 700,
    bold: 900,
  },
})

`InitializeColorMode`

this component can be rendered in HTML before the main application to help prevent the flash of colors that can occur during rehydration.

Usage

<InitializeColorMode />

This component is used internally by gatsby-plugin-theme-ui, but if you’re using Next.js or another React framework with static or server-side rendering, you’ll want to add it to the root level of your application.

Components

For component API docs, see Components.

Edit the page on GitHub

Hooks

Theme Specification