Skip to content
Theme UI

Merging Themes

Sometimes it's useful to split a theme across multiple files, use a preset as the basis for a custom theme, or combine two or more themes together. Since themes are plain JavaScript objects, any merging strategy will work. This guide shows a few common ways to merge themes together.

Using a preset

To use a preset as the basis for a custom theme, it's recommended that you use a deep merge utility. The theme-ui package exports a preconfigured version of the deepmerge package that can be used for this.

// example theme based on preset-future
import future from '@theme-ui/preset-future'
import { merge } from 'theme-ui'
export default merge(future, {
fonts: {
body: 'Montserrat, sans-serif',

Multiple files

While there is absolutely nothing wrong with keeping an entire theme in a single file, you can split a theme into multiple files (or modules).

// example theme/colors.js
export default {
text: '#000',
background: '#fff',
primary: '#07c',
// example theme/fonts.js
export default {
body: 'system-ui, sans-serif',
heading: 'Baskerville, Georgia, serif',
monospace: 'Menlo, monospace',
// example theme/index.js
import colors from './colors'
import fonts from './fonts'
export default {
Edit the page on GitHub
Using without MDX