theme-ui

library0.17.4jsnpmunverified

Theme UI is a robust library for constructing themeable user interfaces, leveraging constraint-based design principles to build cohesive design systems, component libraries, and web applications. It serves as the spiritual successor and next evolution of Styled System, offering a flexible API designed for developer ergonomics. The current stable version is 0.17.4. While specific release cadences for major versions aren't fixed, the project sees active development with frequent minor and develop releases, indicating an ongoing commitment to bug fixes and incremental improvements on the 0.x branch. Key differentiators include its powerful `sx` prop for direct, theme-based styling, broad compatibility with virtually any UI component library, built-in support for dark modes, primitive page layout components, and deep integration with popular tools like Gatsby and MDX for content styling. It is built on Emotion for efficient scoped styles and adheres to a standard Theme Specification, promoting interoperability and a consistent design language across projects, making it ideal for large-scale design system implementation.

web-framework serialization

npm install theme-ui

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · THEME-UI

theme-ui

web-frameworkjavascriptv0.17.4

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ThemeProvider

✓ import { ThemeProvider } from 'theme-ui'

✗ const { ThemeProvider } = require('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

✓ import { Box } from 'theme-ui'

✗ 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

✓ import { useThemeUI } from 'theme-ui'

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

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

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;

Debug

Known issues

gotchaTheme 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>`.

affects: >=0.1.0

gotchaThe `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.

affects: >=0.1.0

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

affects: >=0.1.0

breakingTheme 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`.

affects: <0.17.0

Errors

Common errors & fixes

Error: No ThemeProvider found.

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)

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.

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

Upgrade

Version history

0.17.4latest on npm

Audit

Dependencies

@emotion/reactrequiredRequired for the underlying CSS-in-JS styling engine.

reactrequiredCore React library for UI components.

Agent activity

11 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/system-ui/theme-ui ↗

packagehttps://www.npmjs.com/package/theme-ui ↗

homepagehttps://theme-ui.com ↗