# gatsby-plugin-theme-ui

> Gatsby plugin for adding Theme UI context

Latest version **0.17.4** (published 2026-01-02) · MIT license · 0 weekly downloads

## Install

```sh
npm install gatsby-plugin-theme-ui
pnpm add gatsby-plugin-theme-ui
yarn add gatsby-plugin-theme-ui
bun add gatsby-plugin-theme-ui
```

## Health

**Score 50/100 (C)** — status: stable.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.17.4 |
| Published | 2026-01-02 |
| First published | 2019-05-23 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 19.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 5399 |
| Author | Brent Jackson |
| Maintainers | jxnblk, johno, hasparus, lachlanjc |
| Keywords | gatsby, gatsby-plugin, gatsby-theme, theme-ui |

## Links

- npm: https://www.npmjs.com/package/gatsby-plugin-theme-ui
- Repository: https://github.com/system-ui/theme-ui
- Homepage: https://github.com/system-ui/theme-ui#readme
- Issues: https://github.com/system-ui/theme-ui/issues
- npm.io page: https://npm.io/package/gatsby-plugin-theme-ui

## Recent versions

- 0.17.4 (latest) — 2026-01-02
- 0.17.2-develop.1 (develop) — 2025-02-14
- 0.16.2-scale-tuples.0 (canary) — 2023-09-26
- 0.6.0-alpha.8 (next) — 2021-03-19
- 0.4.0-highlight.0 (highlight) — 2020-05-08
- 0.1.3-0.0 (alpha) — 2019-06-05
- 0.17.2 — 2025-02-14
- 0.17.2-develop.0 — 2024-12-18
- 0.17.1 — 2024-10-24
- 0.17.1-develop.0 — 2024-10-24
- 0.17.0 — 2024-10-18
- 0.17.0-develop.1 — 2024-10-18
- 0.17.0-develop.0 — 2024-10-18
- 0.16.2 — 2024-02-19
- 0.16.2-develop.5 — 2024-02-19
- … 454 more at https://npm.io/package/gatsby-plugin-theme-ui/versions

## README

# gatsby-plugin-theme-ui

Gatsby plugin for adding Theme UI context

```sh
npm i theme-ui @theme-ui/mdx gatsby-plugin-theme-ui @emotion/react @mdx-js/react
```

```js
// 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

| Key                      | Default value | Description                                                                                                                                                                                                                                        |
| ------------------------ | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `prismPreset`            | `null`        | The 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](https://theme-ui.com/packages/prism/). You can also use a package string of your own choosing. |
| `preset`                 | `null`        | This can be a JSON theme object or a string package name. Make sure the package you're requiring is installed in your dependencies.                                                                                                                |
| `injectColorFlashScript` | `true`        | By 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

```js
// 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.

```js filename=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:

```js filename=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:

```js filename=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.

```js filename=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](https://theme-ui.com/packages/presets) to use as a starting
point.

## Color Modes

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

```js filename=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.

```js filename=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

---
_Source: https://npm.io/package/gatsby-plugin-theme-ui · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._