DOCSEARCHbyAlgolia
Submit Docs

Theme UI

website·Indexed 35 days ago

https://theme-ui.com/

A themeable component library and design system for React. It provides a set of primitive components—such as Box, Flex, Text, Button, and Input—along with a powerful sx prop for styling and a variety of design presets including Tailwind, Bootstrap, and Bulma.

Tokens
48.6K
Snippets
277
Records
337
Agent score
72%

What's inside Theme UI

  1. Overview of Theme UI

    Theme UI is a library for building themeable user interfaces based on constraint-based design principles. It allows developers to create custom component libraries, design systems, and web applications with a flexible API. Key features include a theme-aware sx prop for CSS, over 30 built-in primitive UI components, built-in dark mode support, and mobile-first responsive styles.

  2. Use the Grid component for tiled layouts

    The Grid component in Theme UI is used to arrange direct child elements in a tiled CSS grid layout. It supports responsive array syntax for all its layout props to enable mobile-first design.
    import { Grid, Box } from 'theme-ui'

<Grid gap={2} columns={[2, null, 4]}>
  <Box bg="primary">Box</Box>
  <Box bg="muted">Box</Box>
  <Box bg="primary">Box</Box>
  <Box bg="muted">Box</Box>
</Grid>

  3. Use built-in Theme UI components

    Theme UI provides built-in UI components for layouts, grids, buttons, and form elements. These can be used as an alternative or in parallel with the JSX pragma to apply theme features to your UI.
    <Box p={4} bg="highlight">
  <Flex sx={{ alignItems: 'center' }}>
    <Heading>Components</Heading>
    <Button ml="auto">Beep</Button>
  </Flex>
</Box>

  4. Understand Theme UI core architecture

    Theme UI is a mini-framework for styling applications built by combining several libraries: Emotion (for isolated CSS and theming context), MDX (for providing styled components to documents without global CSS pollution), and optionally Typography.js (for high-level typographic styles).

  5. Understand the Theme UI theme object structure

    The Theme UI theme object is designed for interoperability and white-labeling. It consists of three primary data types:

    • Scales: Plain objects or arrays containing values for related CSS properties (e.g., a color scale or spacing scale).
    • Variants: Partial style objects used to create stylistic component variations or to make specific parts of an application themeable.
    • Styles: A collection of styles specifically intended for MDX content.

  6. Migrate from Theme UI v0.6 to v0.7

    When upgrading to v0.7, replace deprecated components and hooks to avoid breaking changes. Specifically, replace Styled with Themed and replace the useBodyStyles hook with useRootStyles.

  7. Apply custom media queries in the sx prop

    For complex responsive requirements where array shorthand is insufficient, you can use nested objects with standard CSS media query syntax directly within the sx prop.
    <div
  sx={{
    width: '100%',
    '@media screen and (min-width: 40em)': {
      width: '50%',
    },
  }}
/>

  8. Enrich custom MDX components with Theme UI styles

    To apply styles defined in theme.styles to components passed to the MDX context, use the useThemedStylesWithMdx hook from @theme-ui/mdx. This hook should wrap the components retrieved from useMDXComponents and be passed to the MDXProvider within a ThemeUIProvider.
    import { MDXProvider, useMDXComponents, MDXComponents } from '@mdx-js/react'
import { useThemedStylesWithMdx } from '@theme-ui/mdx'
import { ThemeUIProvider } from 'theme-ui'
import { h2, Note, TweetEmbed } from './components'

const components: MDXComponents = {
  h2,
  Note,
  TweetEmbed,
}

const theme = {
  styles: {
    h2: {
      fontWeight: 700,
    },
  },
}

function Provider({ children }: { children: React.ReactNode }) {
  // Enrich components with theme.styles
  const componentsWithStyles = useThemedStylesWithMdx(
    useMDXComponents(components)
  )

  return (
    <ThemeUIProvider theme={theme}>
      <MDXProvider components={componentsWithStyles}>
        {children}
      </MDXProvider>
    </ThemeUIProvider>
  )
}

  9. Migrate from styled-components to @emotion/styled

    Components written using the styled-components library can typically be converted to use Emotion (which is compatible with Theme UI) by updating the import statement.
    // before
import styled from 'styled-components'

// after
import styled from '@emotion/styled'

  10. Implement CSS keyframe animations in Theme UI

    Theme UI supports CSS keyframes, but does not provide its own keyframes utility. Instead, use the keyframes helper from the @emotion/react library. To implement an animation: create a keyframes variable and then reference that variable within the animation or animationName property of an sx prop.
    import { keyframes } from '@emotion/react'

// 1. Define the animation
const fadeIn = keyframes`
  from { opacity: 0; }
  to { opacity: 1; }
`

// 2. Use it in the sx prop
<Box sx={{ animation: `${fadeIn} 1s backwards` }} />

  12. Install Theme UI v0.13 peer dependencies

    Starting in v0.13, Emotion and @mdx-js/react were moved to peerDependencies to prevent context mismatch bugs and version clashes. You must install these packages explicitly alongside theme-ui.
    npm install theme-ui @emotion/react @emotion/styled @mdx-js/react