Skip to content
Theme UI



The core theme-ui package exports the following modules.


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.



<div css={css(styles)} />
styleObjectObjecta theme-aware style object with support for responsive array values and Styled System prop shortcuts
themeObjectthe Emotion theming context object


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.


/** @jsx jsx */
import { jsx } from 'theme-ui'
export default props => (
color: 'primary',


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.

themeObjectTheming context object
componentsObjectOptional custom MDX components
childrenNodeReact children


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

const context = useThemeUI()


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.


<ThemeProvider theme={theme}>
<ColorMode />


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


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 />
asString or ComponentChanges the underlying rendered element


The BaseStyles component can be used to style child content that isn't generated from MDX. Note that this will increase the CSS specificity of child elements, and you may run into issues with the cascade (i.e. specificity) when using this component.

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


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.


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.


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
Match Media
How it Works