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

yarn add theme-ui @emotion/react

pnpm add 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

yarn add @theme-ui/core @emotion/react

pnpm add @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

Get Started

Core Concepts

Guides

Components

Presets

Installation

Installation

Prerequisites

Install Dependencies

Lightweight Alternative

Setup

Step 1: Create a Theme

Step 2: Add the Provider

Step 3: Enable the `sx` Prop

TypeScript Support

Verify Installation

Next Steps

Quickstart

​Installation

​Prerequisites

​Install Dependencies

​Lightweight Alternative

​Setup

​Step 1: Create a Theme

​Step 2: Add the Provider

​Step 3: Enable the sx Prop

​TypeScript Support

​Verify Installation

​Next Steps

Quickstart

Installation

Prerequisites

Install Dependencies

Lightweight Alternative

Setup

Step 1: Create a Theme

Step 2: Add the Provider

Step 3: Enable the `sx` Prop

TypeScript Support

Verify Installation

Next Steps