Quickstart Guide

This guide will walk you through creating a simple themed button component using Theme UI. You’ll learn the fundamentals of the sx prop, theme values, and variant styling.

This guide assumes you’ve already installed Theme UI and set up the ThemeUIProvider in your application.

Create Your First Themed Component

Create a theme file

First, let’s create a theme with button styles. Create or update your theme.js file:

theme.js

export default {
  // Font scales
  fonts: {
    body: 'system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", sans-serif',
  },
  fontSizes: [
    12, 14, 16, 20, 24, 32, 48, 64
  ],
  fontWeights: {
    body: 400,
    bold: 700,
  },
  
  // Spacing scale
  space: [
    0, 4, 8, 16, 32, 64, 128, 256
  ],
  
  // Color palette
  colors: {
    text: '#000',
    background: '#fff',
    primary: '#07c',
    secondary: '#639',
    muted: '#f6f6f9',
  },
  
  // Button variants
  buttons: {
    primary: {
      color: 'white',
      bg: 'primary',
      fontWeight: 'bold',
      '&:hover': {
        bg: 'secondary',
      },
    },
    secondary: {
      color: 'text',
      bg: 'muted',
    },
  },
}

This theme defines:

Font and spacing scales that components can reference by index
A color palette with semantic names
Button variants with different styles

Add the ThemeUIProvider

Wrap your application with the provider. If you haven’t done this yet:

App.jsx

import { ThemeUIProvider } from 'theme-ui'
import theme from './theme'
import Button from './Button'

export default function App() {
  return (
    <ThemeUIProvider theme={theme}>
      <div>
        <h1>My Themed App</h1>
        <Button />
      </div>
    </ThemeUIProvider>
  )
}

Create a custom button component

Create a new file called Button.jsx and add the JSX pragma at the top:

Button.jsx

/** @jsxImportSource theme-ui */

export default function Button() {
  return (
    <button
      sx={{
        // Reference theme values
        color: 'white',
        bg: 'primary',
        border: 0,
        borderRadius: 4,
        
        // Use spacing scale
        px: 3,  // theme.space[3] = 16px
        py: 2,  // theme.space[2] = 8px
        
        // Use font scale
        fontSize: 2,  // theme.fontSizes[2] = 16px
        fontWeight: 'bold',
        
        // Add interactivity
        cursor: 'pointer',
        '&:hover': {
          bg: 'secondary',
        },
      }}
    >
      Click Me
    </button>
  )
}

Don’t forget the /** @jsxImportSource theme-ui */ pragma! Without it, the sx prop won’t work.

Use responsive styles

Make your button responsive by using arrays for style values:

Button.jsx

/** @jsxImportSource theme-ui */

export default function Button() {
  return (
    <button
      sx={{
        color: 'white',
        bg: 'primary',
        border: 0,
        borderRadius: 4,
        
        // Responsive padding: small on mobile, larger on desktop
        px: [2, 3, 4],  // 8px, 16px, 32px
        py: [1, 2, 3],  // 4px, 8px, 16px
        
        // Responsive font size
        fontSize: [1, 2, 3],  // 14px, 16px, 20px
        fontWeight: 'bold',
        
        cursor: 'pointer',
        '&:hover': {
          bg: 'secondary',
        },
      }}
    >
      Click Me
    </button>
  )
}

The array syntax applies styles mobile-first:

First value: all viewports
Second value: first breakpoint and up (typically 40em/640px)
Third value: second breakpoint and up (typically 52em/832px)

Use theme variants

Instead of defining all styles inline, reference the button variant from your theme:

Button.jsx

/** @jsxImportSource theme-ui */

export default function Button({ variant = 'primary', children }) {
  return (
    <button
      sx={{
        // Apply the variant from theme.buttons
        variant: `buttons.${variant}`,
        
        // Add base styles
        appearance: 'none',
        display: 'inline-block',
        textAlign: 'center',
        lineHeight: 'inherit',
        textDecoration: 'none',
        fontSize: 'inherit',
        px: 3,
        py: 2,
        border: 0,
        borderRadius: 4,
        cursor: 'pointer',
      }}
    >
      {children || 'Click Me'}
    </button>
  )
}

Now you can use different button styles:

<Button variant="primary">Primary Button</Button>
<Button variant="secondary">Secondary Button</Button>

Using Theme UI Components

Theme UI also provides pre-built components. Here’s how to use the built-in Button component:

/** @jsxImportSource theme-ui */
import { Button } from 'theme-ui'

export default function App() {
  return (
    <div>
      <Button>Primary Button</Button>
      <Button variant="secondary" sx={{ ml: 2 }}>
        Secondary Button
      </Button>
    </div>
  )
}

The built-in Button component:

Automatically references theme.buttons variants
Supports the sx prop for custom overrides
Includes default styles for common button properties
Uses variant="primary" by default

You can use the sx prop on Theme UI components to override or extend variant styles.

Complete Example

Here’s a complete working example with a theme, provider, and themed button:

export default {
  fonts: {
    body: 'system-ui, sans-serif',
  },
  fontSizes: [12, 14, 16, 20, 24, 32],
  space: [0, 4, 8, 16, 32, 64],
  colors: {
    text: '#000',
    background: '#fff',
    primary: '#07c',
    secondary: '#639',
    muted: '#f6f6f9',
  },
  buttons: {
    primary: {
      color: 'white',
      bg: 'primary',
      '&:hover': {
        bg: 'secondary',
      },
    },
    secondary: {
      color: 'text',
      bg: 'muted',
    },
  },
}

import { ThemeUIProvider } from 'theme-ui'
import theme from './theme'
import MyButton from './MyButton'

export default function App() {
  return (
    <ThemeUIProvider theme={theme}>
      <div style={{ padding: '20px' }}>
        <h1>Theme UI Quickstart</h1>
        <MyButton variant="primary">Primary</MyButton>
        <MyButton variant="secondary">Secondary</MyButton>
      </div>
    </ThemeUIProvider>
  )
}

/** @jsxImportSource theme-ui */

export default function MyButton({ variant = 'primary', children }) {
  return (
    <button
      sx={{
        variant: `buttons.${variant}`,
        px: 3,
        py: 2,
        fontSize: 2,
        fontWeight: 'bold',
        border: 0,
        borderRadius: 4,
        cursor: 'pointer',
        mr: 2,
      }}
    >
      {children}
    </button>
  )
}

Key Concepts Learned

The sx prop: Apply styles that reference your theme
Theme values: Use semantic names and scale indices instead of hard-coded values
Variants: Define reusable style patterns in your theme
Responsive styles: Use arrays for mobile-first responsive design
JSX pragma: Enable the sx prop with /** @jsxImportSource theme-ui */

Next Steps

Now that you’ve built your first themed component, explore more features:

Color Modes

Add dark mode support to your application

Components

Explore Theme UI’s built-in components

Theming

Learn about the theme specification

Responsive Styles

Master responsive design patterns

Get Started

Core Concepts

Guides

Components

Presets

Quickstart

Quickstart Guide

Create Your First Themed Component

Using Theme UI Components

Complete Example

Key Concepts Learned

Next Steps

Color Modes

Components

Theming

Responsive Styles

​Quickstart Guide

​Create Your First Themed Component

​Using Theme UI Components

​Complete Example

​Key Concepts Learned

​Next Steps

Color Modes

Components

Theming

Responsive Styles

Quickstart Guide

Create Your First Themed Component

Using Theme UI Components

Complete Example

Key Concepts Learned

Next Steps