Theme UI

Common errors

• Error: No ThemeProvider found.

  cause Theme UI components were rendered without being wrapped in a ThemeProvider.
  fix Wrap your root component or the section using Theme UI with `<ThemeProvider theme={yourTheme}>`.

• Property 'sx' does not exist on type 'IntrinsicElements...' (TypeScript error)

  cause TypeScript compiler cannot find the `sx` prop definition for standard HTML elements or custom components.
  fix Ensure you have `@types/theme-ui` installed and that your `tsconfig.json` includes `theme-ui` types. You might also need to configure a custom `jsx` pragma in your `tsconfig.json` or Babel configuration.

• React Hook 'useThemeUI' cannot be called inside a class component. React Hooks can only be called inside of a function component.

  cause `useThemeUI` is a React Hook and can only be used within functional components or other custom hooks, not within class components.
  fix Refactor your component to be a functional component or pass the theme down as props from a parent functional component that uses `useThemeUI`.

Warnings

• gotcha Theme UI relies heavily on a `ThemeProvider` at the root of your application. Components styled with `sx` or `variant` props will not function correctly or throw errors if they are rendered outside of a `ThemeProvider` context.
  Fix: Ensure your entire application or at least the part utilizing Theme UI components is wrapped within `<ThemeProvider theme={yourTheme}>...</ThemeProvider>`.
• gotcha The `sx` prop in Theme UI does not directly override all CSS properties in the same way inline styles might. It's designed to work with theme scales and provides shorthands. Mixing `sx` with direct CSS or `className` from other libraries can lead to unexpected specificity issues.
  Fix: Prefer using `sx` for all your styling when working with Theme UI to leverage theme constraints and ensure consistent behavior. For custom, non-theme-driven styles, consider using Emotion's `css` prop or a dedicated component.
• gotcha When upgrading Theme UI, particularly across minor versions (e.g., from 0.16 to 0.17), always review the release notes. While 0.x releases generally aim for backward compatibility, minor breaking changes or API deprecations can occur due to its active development and experimental features.
  Fix: Consult the official Theme UI documentation and GitHub release notes before and after upgrading to identify any specific migration steps or API changes required for your codebase.
• breaking Theme UI requires `react` version 18 or higher and `@emotion/react` version 11.1.1 or higher as peer dependencies. Older versions of these packages will cause runtime errors or compilation failures.
  Fix: Upgrade your `react` and `@emotion/react` packages to satisfy the peer dependency requirements: `npm install react@^18.0.0 @emotion/react@^11.1.1`.

Install

• npm install theme-ui npm
• yarn add theme-ui yarn
• pnpm add theme-ui pnpm

Imports

• ThemeProvider
  wrong:

  const { ThemeProvider } = require('theme-ui')

  correct:

  import { ThemeProvider } from 'theme-ui'

  Essential for providing theme context to all Theme UI components. CommonJS `require` syntax is generally not recommended for modern Theme UI applications targeting browser environments due to its ESM-first distribution and React 18+ requirements.
• Box
  wrong:

  import Box from 'theme-ui'

  correct:

  import { Box } from 'theme-ui'

  A fundamental primitive component for layout and styling provided by Theme UI. Theme UI primarily uses named exports for its components, so default imports will not work.
• useThemeUI
  wrong:

  const useThemeUI = require('theme-ui').useThemeUI

  correct:

  import { useThemeUI } from 'theme-ui'

  React hook for accessing the theme object and Theme UI context programmatically within functional components. This hook must be called within a component that is a descendant of a `ThemeProvider`.

Quickstart

This quickstart demonstrates setting up a `ThemeProvider` with a custom theme and using basic components like `Box` and `Text` with the `sx` prop for styling, including responsive styles and dark mode support via theme configuration. This code is runnable in a React environment.

import React from 'react';
import { ThemeProvider, Box, Text } from 'theme-ui';

const customTheme = {
  colors: {
    text: '#000',
    background: '#fff',
    primary: '#07c',
    secondary: '#05a',
    modes: {
      dark: {
        text: '#fff',
        background: '#000',
        primary: '#0cf',
        secondary: '#09f',
      },
    },
  },
  fonts: {
    body: 'system-ui, sans-serif',
    heading: 'Georgia, serif',
  },
  text: {
    heading: {
      fontFamily: 'heading',
      lineHeight: 'heading',
      fontWeight: 'heading',
      fontSize: [4, 5, 6],
    },
  },
  buttons: {
    primary: {
      color: 'background',
      bg: 'primary',
      '&:hover': {
        bg: 'secondary',
      },
    },
  },
  styles: {
    root: {
      fontFamily: 'body',
      color: 'text',
      bg: 'background',
    },
  },
};

const App = () => (
  <ThemeProvider theme={customTheme}>
    <Box sx={{
      maxWidth: 960,
      mx: 'auto',
      px: [3, 4],
      py: 4,
      bg: 'background',
      color: 'text',
    }}>
      <Text as="h1" sx={{ variant: 'text.heading', color: 'primary' }}>
        Welcome to Theme UI!
      </Text>
      <Text sx={{ fontSize: [2, 3] }}>
        This is an example of a themed application using Theme UI's `sx` prop and `ThemeProvider`.
        The styles are derived from the `customTheme` object, enabling responsive and consistent design.
      </Text>
      <Box as="button" sx={{ variant: 'buttons.primary', mt: 4, p: 3, borderRadius: 4 }}>
        Click Me
      </Box>
    </Box>
  </ThemeProvider>
);

export default App;