How it Works

Theme UI combines several libraries together to form a mini-framework for styling applications.

Theme UI is built with:

• Emotion: used to generate isolated CSS with theming context
• MDX: used to provide custom Emotion styled components to MDX documents, without polluting the global CSS scope
• Typography.js: optionally used for creating rich typographic styles with a simple, high-level API

ThemeUIProvider

The Theme UI ThemeUIProvider component wraps Emotion's ThemeProvider, which adds the theme object to context for use with Emotion.

Custom Components

When using the components prop to add custom MDX components, each component is wrapped with the sx prop to allow the component to pick up values from the theme.styles object.

JSX Pragma

The Theme UI JSX function wraps the Emotion JSX function, converting the sx prop to a call to @theme-ui/css. The two examples below yield the same results:

// with Emotion's JSX function
// this is typically handled with the Emotion Babel preset
/** @jsxImportSource @emotion/react */
import { css } from 'theme-ui'

export default (props) => (
  <div
    {...props}
    css={css({
      color: 'white',
      bg: 'primary',
      fontSize: 4,
    })}
  />
)

// with Theme UI's JSX function
/** @jsxImportSource theme-ui */

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