> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/system-ui/theme-ui/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install Theme UI and configure it in your React application

# 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.

<CodeGroup>
  ```bash npm theme={null}
  npm install theme-ui @emotion/react
  ```

  ```bash yarn theme={null}
  yarn add theme-ui @emotion/react
  ```

  ```bash pnpm theme={null}
  pnpm add theme-ui @emotion/react
  ```
</CodeGroup>

<Note>
  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](https://github.com/system-ui/theme-ui/tree/develop/packages/core) package instead.
</Note>

## Lightweight Alternative

For a minimal installation without color modes or components:

<CodeGroup>
  ```bash npm theme={null}
  npm install @theme-ui/core @emotion/react
  ```

  ```bash yarn theme={null}
  yarn add @theme-ui/core @emotion/react
  ```

  ```bash pnpm theme={null}
  pnpm add @theme-ui/core @emotion/react
  ```
</CodeGroup>

## 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](https://system-ui.com/theme).

Create a file called `theme.js` (or `theme.ts` for TypeScript):

```js theme.js theme={null}
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.

```jsx App.jsx theme={null}
import { ThemeUIProvider } from 'theme-ui'
import theme from './theme'

export default function App() {
  return (
    <ThemeUIProvider theme={theme}>
      {/* Your app components */}
    </ThemeUIProvider>
  )
}
```

<Note>
  The `ThemeUIProvider` should be placed at the root of your application to make the theme available to all components.
</Note>

### 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:

```jsx theme={null}
/** @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.

<Warning>
  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`.
</Warning>

## TypeScript Support

Theme UI includes full TypeScript definitions. No additional setup is required for TypeScript support.

```tsx theme={null}
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:

```jsx test.jsx theme={null}
/** @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

<Card title="Quickstart" icon="rocket" href="/quickstart">
  Learn how to create your first themed component
</Card>