Skip to content
Theme UI
GitHub

API

theme-ui

The core theme-ui package exports the following modules.

css

The css utility comes from the @styled-system/css package and 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 Styled System CSS 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

jsx

The jsx export is a React create element function intended for use with a custom pragma comment. It adds support for the sx prop, which uses Emotion's create element function internally and parses style objects with the Theme UI css utility.

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.

PropTypeDescription
themeObjectTheming context object
componentsObjectOptional custom MDX components
childrenNodeReact children

useThemeUI

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

const context = useThemeUI()

ColorMode

The ColorMode component applies foreground and background color to the <body> element, based on the color modes defined in a theme. It is also used in gatsby-plugin-theme-ui for helping reduce flashes of style changes on page load.

Usage

<ThemeProvider theme={theme}>
<ColorMode />
{props.children}
</ThemeProvider>

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

Styled

The Styled 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`
<Styled.h1 />
PropTypeDescription
asString or ComponentChanges the underlying rendered element

Layout

The Layout component is the root-level page layout component, with flexbox styles applied.

See the layout components docs for more info.

The Header component is intended for use as a page header.

Main

The Main component is intended for use as a wrapper around the main page area. It includes flexbox styles to wrap the Container component and optional sidebar elements.

Container

The Container component includes a max-width and marginX: 'auto' for horizontal centering.

The Footer component is intended for use as a page footer.

Edit the page on GitHub
Previous:
Hooks
Next:
How it Works