Skip to content
Theme UI
GitHub

Theming

Theming with Theme UI is based on the System UI Theme Spec with an additional theme.styles object for styling MDX elements and other components. By adhering to a standard Theme Specification, Theme UI is designed to be interoperable with as many other libraries as possible.

Colors

Add a theme.colors object to provide colors for a theme. In order to make color palettes as portable and interoperable as possible, the following color keys should be used for defining a base set of colors:

KeyDescription
textbody color
backgroundbody background color
primaryprimary button and link color
secondarysecondary color - can be used for hover states
accenta contrast color for emphasizing UI
muteda gray or subdued color for decorative purposes

Beyond these base colors, any additional values can be added to a theme to augment the base color palette.

Color Modes

Multiple color modes, i.e. dark mode, can be handled with a nested modes object that matches the shape of the default colors.

// example colors with dark mode
colors: {
text: '#000',
background: '#fff',
primary: '#07c',
modes: {
dark: {
text: '#fff',
background: '#000',
primary: '#0cf',
}
}
}

Learn more in the color mode docs.

Typography

Core typographic values can be stored in the following theme keys:

  • fonts (font families)
  • fontSizes
  • fontWeights
  • lineHeights
  • letterSpacings
// example theme object
{
colors,
fonts: {
body: 'system-ui, sans-serif',
heading: 'Georgia, serif',
monospace: 'Menlo, monospace',
},
fontSizes: [
12, 14, 16, 20, 24, 32, 48, 64
],
fontWeights: {
body: 400,
heading: 700,
bold: 700,
},
lineHeights: {
body: 1.5,
heading: 1.125,
},
letterSpacings: {
body: 'normal',
caps: '0.2em',
},
}

Styles

Styles for elements rendered in MDX can be added to the theme.styles object. This is the primary API for applying typographic styles in markdown content. Styles within this object have access to other values in the theme object, such as colors, fonts, and space.

// example theme styles
{
colors: {
text: '#000',
background: '#fff',
primary: '#07c',
},
fonts: {
body: 'system-ui, sans-serif',
heading: 'Georgia, serif',
},
fontWeights: {
body: 400,
heading: 700,
},
styles: {
h1: {
fontSize: 32,
fontFamily: 'heading',
fontWeight: 'heading',
color: 'primary',
mt: 4,
mb: 2,
},
}
}

Breakpoints

To configure the default breakpoints used in responsive array values, add a breakpoints array to your theme. Each breakpoint should be a string with a CSS length unit included. These values will be used to generate mobile-first (i.e. min-width) media queries, which can then be used to apply responsive styles.

// example custom breakpoints
{
breakpoints: [
'40em', '56em', '64em',
],
}

Example

The following example is from the Base Preset.

// example base theme from @theme-ui/presets
const heading = {
fontFamily: 'heading',
lineHeight: 'heading',
fontWeight: 'heading',
}
export const base = {
breakpoints: ['40em', '52em', '64em'],
space: [0, 4, 8, 16, 32, 64, 128, 256, 512],
fonts: {
body: 'system-ui, sans-serif',
heading: 'inherit',
monospace: 'Menlo, monospace',
},
fontSizes: [12, 14, 16, 20, 24, 32, 48, 64, 96],
fontWeights: {
body: 400,
heading: 700,
bold: 700,
},
lineHeights: {
body: 1.5,
heading: 1.125,
},
colors: {
text: '#000',
background: '#fff',
primary: '#07c',
secondary: '#30c',
muted: '#f6f6f6',
},
styles: {
root: {
fontFamily: 'body',
lineHeight: 'body',
fontWeight: 'body',
},
h1: {
...heading,
fontSize: 5,
},
h2: {
...heading,
fontSize: 4,
},
h3: {
...heading,
fontSize: 3,
},
h4: {
...heading,
fontSize: 2,
},
h5: {
...heading,
fontSize: 1,
},
h6: {
...heading,
fontSize: 0,
},
pre: {
fontFamily: 'monospace',
overflowX: 'auto',
code: {
color: 'inherit',
},
},
code: {
fontFamily: 'monospace',
fontSize: 'inherit',
},
table: {
width: '100%',
borderCollapse: 'separate',
borderSpacing: 0,
},
th: {
textAlign: 'left',
borderBottomStyle: 'solid',
},
td: {
textAlign: 'left',
borderBottomStyle: 'solid',
},
},
}

For more information on the Theme UI theme object, see the Theme Specification docs.

Edit the page on GitHub
Previous:
Getting Started
Next:
The sx Prop