Skip to content
Theme UI
GitHub

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'

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.

PropTypeDescription
themeObjectTheming context object
componentsObjectOptional custom MDX components
childrenNodeReact 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)} />
ArgumentTypeDescription
styleObjectObjecta theme-aware style object with support for responsive array values and Styled System prop shortcuts
themeObjectthe 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
Previous:
Hooks
Next:
Theme Specification