API

theme-ui

The core theme-ui package exports the following modules.

/jsx-runtime

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'

jsx

The jsx export is a React create element function for the classic JSX runtime intended for use with a custom pragma comment. It adds support for the sx prop in the same way like the /jsx-runtime entrypoint.

Usage:

/** @jsx jsx */
import { jsx } from 'theme-ui'

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

ThemeProvider

The ThemeProvider component is a wrapper around Emotion's ThemeProvider 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.

useThemeUI

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

const context = useThemeUI()

Context

The React context used in Theme UI.

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()

Themed

The Themed export is an object of Emotion styled components that map to keys in the theme.styles object. Each component will pick up styles from its corresponding theme object. These are primarily meant to be used as a mechanism to use styles defined in a theme object outside of MDX.

// picks up styles from `theme.styles.h1`
<Themed.h1 />

BaseStyles

The BaseStyles component can be used to style child content that isn't generated from MDX.

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

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

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

Used internally by gatsby-plugin-theme-ui, 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 />

components

An object of styled MDX components for use with MDXProvider.

Components

For component API docs, see Components