Skip to main content

​
Installation

Get started with Theme UI by installing the package and its peer dependencies.

​
Prerequisites

Theme UI requires the following in your project:
  • Node.js: Version 18.0.0 or higher
  • React: Version 18 or higher

​
Install Dependencies

Theme UI has a peer dependency on @emotion/react, which must be installed alongside the main package. 
npm install theme-ui @emotion/react
The theme-ui package includes all features: the sx prop, color modes, and UI components. If you don’t need color modes or components, you can install the lighter @theme-ui/core package instead.

​
Lightweight Alternative

For a minimal installation without color modes or components: 
npm install @theme-ui/core @emotion/react

​
Setup

After installation, set up Theme UI in your application by creating a theme and wrapping your app with the ThemeUIProvider.

​
Step 1: Create a Theme

Create a theme file that defines your design tokens. The theme object follows the System UI Theme Specification. Create a file called theme.js (or theme.ts for TypeScript):
theme.js
export default {
  fonts: {
    body: 'system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", sans-serif',
    heading: '"Avenir Next", sans-serif',
    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,
  },
  space: [
    0, 4, 8, 16, 32, 64, 128, 256, 512
  ],
  colors: {
    text: '#000',
    background: '#fff',
    primary: '#33e',
    secondary: '#119',
    muted: '#f6f6f6',
  },
  buttons: {
    primary: {
      color: 'white',
      bg: 'primary',
    },
    secondary: {
      color: 'text',
      bg: 'secondary',
    },
  },
}

​
Step 2: Add the Provider

Wrap your application with the ThemeUIProvider component and pass in your theme object.
App.jsx
import { ThemeUIProvider } from 'theme-ui'
import theme from './theme'

export default function App() {
  return (
    <ThemeUIProvider theme={theme}>
      {/* Your app components */}
    </ThemeUIProvider>
  )
}
The ThemeUIProvider should be placed at the root of your application to make the theme available to all components.

​
Step 3: Enable the sx Prop

To use the sx prop in your components, add the JSX pragma comment at the top of each file: 
/** @jsxImportSource theme-ui */

export default function MyComponent() {
  return (
    <div
      sx={{
        color: 'primary',
        bg: 'background',
        p: 3,
      }}
    >
      Themed content
    </div>
  )
}
The /** @jsxImportSource theme-ui */ pragma tells your build tool to use Theme UI’s custom JSX function, which enables the sx prop.
The pragma is required for the sx prop to work. Without it, the sx prop will be ignored. You need to add it to every file where you want to use sx.

​
TypeScript Support

Theme UI includes full TypeScript definitions. No additional setup is required for TypeScript support. 
import { Theme } from 'theme-ui'

const theme: Theme = {
  colors: {
    text: '#000',
    background: '#fff',
    primary: '#07c',
  },
}

​
Verify Installation

To verify that Theme UI is installed correctly, create a simple component using the sx prop:
test.jsx
/** @jsxImportSource theme-ui */

export default function Test() {
  return (
    <div
      sx={{
        fontSize: 4,
        color: 'primary',
        bg: 'muted',
        p: 3,
      }}
    >
      If this text is styled, Theme UI is working!
    </div>
  )
}
If the component renders with styles from your theme, you’re ready to start building!

​
Next Steps

Quickstart

Learn how to create your first themed component

Build docs developers (and LLMs) love

Get started for freeTalk to us