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.
Prop | Type | Description |
---|---|---|
theme | Object | Theming context object |
components | Object | Optional custom MDX components |
children | Node | React 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)} />
Argument | Type | Description |
---|---|---|
styleObject | Object | a theme-aware style object with support for responsive array values and Styled System prop shortcuts |
theme | Object | the 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