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.
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.
The Theme UI plugin uses the component shadowing API to add the theme object context to your site.
src/gatsby-plugin-theme-ui directory in your project, and add an
index.js file to export a theme object.
colors object to the file created above 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.
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.
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 a Gatsby theme that uses
gatsby-plugin-theme-ui is installed in a site,
src/gatsby-plugin-theme-ui/index.js file will completely override the default styles.
This is intended to give full control to the person using the theme.
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, it can be imported and merged with any other values you would like to customize.
The following is an example of extending the configuration from
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.