Theme UI is a library for styling React apps with user-configurable design constraints. It allows you to style any component in your application with typographic, color, and layout values defined in a shared theme object. Theme UI is currently used in Gatsby’s official themes, but it can be used in any Gatsby site or React application. It includes the Emotion CSS-in-JS library along with additional utilities for styling MDX and using configurations and themes from Typography.js.
Using Theme UI in Gatsby
Theme UI includes the
gatsby-plugin-theme-ui package to better integrate with your Gatsby project.
Install the following packages to add Theme UI.
After installing the dependencies, add the following to your
Theme UI uses a
theme configuration object to provide color, typography, layout, and other shared stylistic values through React context.
This allows components within your site to add styles based on a predefined set of values.
There are two ways to add a theme to your site: using configuration options in
gatsby-plugin-theme-ui, or local shadowing.
gatsby-plugin-theme-ui allows for optional configuration. One of the options you can pass in is
preset. Preset is a base theme object you’d like your site to use.
preset can be a JSON object or a string package name that the plugin will require for you.
If you’re passing in a string package name you need to make sure that the dependency is installed.
Alternatively, you could do the same thing and require the package yourself. This is necessary if you’re referencing a local package that isn’t available publicly.
preset operates as your base theme and any local shadowed styles will automatically merge with it. Local styles are considered more specific and will override base styles where necessary.
The Theme UI plugin uses the component shadowing API to add the theme object context to your site. Shadowing is the ability to create a file in the same location as the theme you’re leveraging and override the original file’s content.
In this case, that location is
src/gatsby-plugin-theme-ui. So, create that directory in your project and add an
index.js file to export a theme object.
Creating a theme object
src/gatsby-plugin-theme-ui directory in your project and add an
index.js file to export a theme object. Add a
colors object to the file to store the color palette for your site.
Next add some base typographic values.
Next add values for use in margin and padding.
Feel free to include as many additional values as you’d like in your theme. Read more about theming in the Theme UI documentation.
Adding styles to elements
Theme UI uses a custom function to add support for the Theme UI
sx prop in JSX.
This custom function is enabled by including a comment on the top of the file:
sx prop is used to style elements by referencing values from the theme object.
Using Theme UI in a Gatsby theme
When using Theme UI in a Gatsby theme, it’s important to understand how the
gatsby-plugin-theme-ui package handles theme objects from multiple Gatsby themes and sites.
If multiple themes are installed in the same site, the one defined last in your
plugins array will take precedence.
To extend an existing Theme UI configuration from a theme you’ll need to find out how the base theme is passing styles. If it’s using a
preset, as the
gatsby-theme-blog package does, any shadowed files are merged automatically. This can be discovered by looking at the theme source code in
node_modules or on GitHub.
If the theme itself is shadowing styles without a preset, you’ll want to merge those styles with your local ones. Here’s an example using Theme UI’s
Styling MDX content
Theme UI includes a way to style elements in MDX documents without the need to add global CSS to your site. This is useful for authoring Gatsby themes that can be installed alongside other themes.
In your Theme UI configuration, add a
styles object to target elements rendered from MDX.
With the example above, any
<a> elements rendered from an MDX file will include these base styles.
To learn more about using Theme UI in your project, see the official Theme UI website.