Getting Started

Install Theme UI.

npm i theme-ui

Create a theme object to include custom color, typography, and layout values.

// example theme.js
export default {
  fonts: {
    body: 'system-ui, sans-serif',
    heading: '"Avenir Next", sans-serif',
    monospace: 'Menlo, monospace',
  },
  colors: {
    text: '#000',
    background: '#fff',
    primary: '#33e',
  },
}

Add the theme to your application with the ThemeProvider, passing in the theme object as a prop.

// basic usage
import React from 'react'
import { ThemeProvider } from 'theme-ui'
import theme from './theme'
export default props => (
  <ThemeProvider theme={theme}>{props.children}</ThemeProvider>
)

sx prop

Use the sx prop throughout your application to add styles based on your theme to any component. Enable the sx prop by adding the /** @jsx jsx */ comment to the top of your file and importing jsx from Theme UI.

The sx prop lets you add any valid CSS to an element, while using values from your theme to keep styles consistent. You can think of the style object that the sx prop accepts as a superset of CSS.

/** @jsx jsx */
import { jsx } from 'theme-ui'
export default props => (
  <div
    sx={{
      fontWeight: 'bold',
      fontSize: 4, // picks up value from `theme.fontSizes[4]`
      color: 'primary', // picks up value from `theme.colors.primary`
    }}>
    Hello
  </div>
)

Responsive styles

The sx prop also supports using arrays as values to change properties responsively with a mobile-first approach.

/** @jsx jsx */
import { jsx } from 'theme-ui'
export default props => (
  <div
    sx={{
      // applies width 100% to all viewport widths,
      // width 50% above the first breakpoint,
      // and 25% above the next breakpoint
      width: ['100%', '50%', '25%'],
    }}
  />
)

If you prefer standard CSS syntax, you can use nested objects for responsive styles as well.

<div
  sx={{
    width: '100%',
    '@media screen and (min-width: 40em)': {
      width: '50%',
    }
  }}
/>

Components

Theme UI includes a library of primitive UI components, which can be completely customized with your theme and include support for variants. You can use variants to encapsulate more complex, component-specific styles that can be changed with props. Import and use these components to handle layout, images, forms, and more.

/** @jsx jsx */
import {
  jsx,
  Box,
  Label,
  Input,
  Button,
} from 'theme-ui'
export default props =>
  <Box sx={{ mb: 4 }}>
    <Label htmlFor='search'>
      Search
    </Label>
    <Input
      id='search'
      name='search'
      {...props}
    />
    <Button>
      Go
    </Button>
  </Box>

See the Components documentation for more.