{"id":12139,"library":"theme-ui","title":"Theme UI","description":"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.","status":"active","version":"0.17.4","language":"javascript","source_language":"en","source_url":"https://github.com/system-ui/theme-ui","tags":["javascript","theme-ui","emotion","mdx","css","styles","css-in-js","typescript"],"install":[{"cmd":"npm install theme-ui","lang":"bash","label":"npm"},{"cmd":"yarn add theme-ui","lang":"bash","label":"yarn"},{"cmd":"pnpm add theme-ui","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for the underlying CSS-in-JS styling engine.","package":"@emotion/react","optional":false},{"reason":"Core React library for UI components.","package":"react","optional":false}],"imports":[{"note":"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.","wrong":"const { ThemeProvider } = require('theme-ui')","symbol":"ThemeProvider","correct":"import { ThemeProvider } from 'theme-ui'"},{"note":"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.","wrong":"import Box from 'theme-ui'","symbol":"Box","correct":"import { Box } from 'theme-ui'"},{"note":"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`.","wrong":"const useThemeUI = require('theme-ui').useThemeUI","symbol":"useThemeUI","correct":"import { useThemeUI } from 'theme-ui'"}],"quickstart":{"code":"import React from 'react';\nimport { ThemeProvider, Box, Text } from 'theme-ui';\n\nconst customTheme = {\n  colors: {\n    text: '#000',\n    background: '#fff',\n    primary: '#07c',\n    secondary: '#05a',\n    modes: {\n      dark: {\n        text: '#fff',\n        background: '#000',\n        primary: '#0cf',\n        secondary: '#09f',\n      },\n    },\n  },\n  fonts: {\n    body: 'system-ui, sans-serif',\n    heading: 'Georgia, serif',\n  },\n  text: {\n    heading: {\n      fontFamily: 'heading',\n      lineHeight: 'heading',\n      fontWeight: 'heading',\n      fontSize: [4, 5, 6],\n    },\n  },\n  buttons: {\n    primary: {\n      color: 'background',\n      bg: 'primary',\n      '&:hover': {\n        bg: 'secondary',\n      },\n    },\n  },\n  styles: {\n    root: {\n      fontFamily: 'body',\n      color: 'text',\n      bg: 'background',\n    },\n  },\n};\n\nconst App = () => (\n  <ThemeProvider theme={customTheme}>\n    <Box sx={{\n      maxWidth: 960,\n      mx: 'auto',\n      px: [3, 4],\n      py: 4,\n      bg: 'background',\n      color: 'text',\n    }}>\n      <Text as=\"h1\" sx={{ variant: 'text.heading', color: 'primary' }}>\n        Welcome to Theme UI!\n      </Text>\n      <Text sx={{ fontSize: [2, 3] }}>\n        This is an example of a themed application using Theme UI's `sx` prop and `ThemeProvider`.\n        The styles are derived from the `customTheme` object, enabling responsive and consistent design.\n      </Text>\n      <Box as=\"button\" sx={{ variant: 'buttons.primary', mt: 4, p: 3, borderRadius: 4 }}>\n        Click Me\n      </Box>\n    </Box>\n  </ThemeProvider>\n);\n\nexport default App;\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Ensure your entire application or at least the part utilizing Theme UI components is wrapped within `<ThemeProvider theme={yourTheme}>...</ThemeProvider>`.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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`.","message":"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.","severity":"breaking","affected_versions":"<0.17.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Wrap your root component or the section using Theme UI with `<ThemeProvider theme={yourTheme}>`.","cause":"Theme UI components were rendered without being wrapped in a ThemeProvider.","error":"Error: No ThemeProvider found."},{"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.","cause":"TypeScript compiler cannot find the `sx` prop definition for standard HTML elements or custom components.","error":"Property 'sx' does not exist on type 'IntrinsicElements...' (TypeScript error)"},{"fix":"Refactor your component to be a functional component or pass the theme down as props from a parent functional component that uses `useThemeUI`.","cause":"`useThemeUI` is a React Hook and can only be used within functional components or other custom hooks, not within class components.","error":"React Hook 'useThemeUI' cannot be called inside a class component. React Hooks can only be called inside of a function component."}],"ecosystem":"npm"}