Skip to content
Theme UI
GitHub

gatsby-plugin-theme-ui

Gatsby plugin for adding Theme UI context

npm i theme-ui gatsby-plugin-theme-ui
// gatsby-config.js
module.exports = {
  plugins: ['gatsby-plugin-theme-ui'],
}

In addition to providing context, this plugin will also prevent a flash of unstyled colors when using color modes.

Options

KeyDefault valueDescription
prismPresetnullThe name of the preset you'd like to use to style code blocks inside your markdown files. The available presets can be found in the theme-ui docs. You can also use a package string of your own choosing.
presetnullThis can be a JSON theme object or a string package name. Make sure the package you're requiring is installed in your dependencies.
injectColorFlashScripttrueBy default, the plugin injects a script tag to prevent color mode flashing. Set this option to false to omit the script. Useful for AMP (Accelerated Mobile Pages) pages.

Note that this plugin assumes the theme object is exported as default.

The theme module you include in options is considered your base theme. Any further customization and shadowing will be merged with it.

Using options

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: 'gatsby-plugin-theme-ui',
      options: {
        prismPreset: 'night-owl',
        preset: '@theme-ui/preset-funk',
      },
    },
  ],
}

Customizing the theme

To customize the theme used in your Gatsby site, shadow the src/gatsby-plugin-theme-ui/index.js module.

src/gatsby-plugin-theme-ui/index.js
const theme = {
  colors: {
    text: '#111',
    background: '#fff',
  },
}
export default theme

Load theme from custom path

If you prefer to load your theme from a custom path (instead of the standard src/gatsby-plugin-theme-ui/index.js), you can require it in your gatsby-config.js file:

gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: 'gatsby-plugin-theme-ui',
      options: {
        preset: require('./src/theme'),
      },
    },
  ],
}

Note that gatsby-config.js does not support ES6 modules, so you should use module.exports in your theme file:

src/theme.js
module.exports = {
  colors: {
    text: '#111',
    background: '#fff',
  },
}

Extending a theme

To extend a Gatsby theme that uses Theme UI, import the base theme and export a new theme object.

src/gatsby-plugin-theme-ui/index.js
import baseTheme from 'gatsby-theme-blog/src/gatsby-plugin-theme-ui'
const theme = {
  ...baseTheme,
  colors: {
    ...baseTheme.colors,
    text: '#111',
    background: '#fff',
  },
}
export default theme

You can also import and use presets from @theme-ui/presets to use as a starting point.

Color Modes

To enable support for multiple color modes, add a nested modes object to theme.colors.

src/gatsby-plugin-theme-ui/index.js
const theme = {
  colors: {
    text: '#000',
    background: '#fff',
    modes: {
      dark: {
        text: '#fff',
        background: '#000',
      },
    },
  },
}
export default theme

Components

Custom MDX components that will receive styles from the theme can be included by adding a src/gatsby-plugin-theme-ui/components.js module.

src/gatsby-plugin-theme-ui/components.js
const components = {
  h1: (props) => (
    <h1 {...props}>
      <a href={`#${props.id}`}>{props.children}</a>
    </h1>
  ),
}
export default components

MIT License

Edit the page on GitHub
Previous:
@theme-ui/editor
Next:
gatsby-theme-style-guide