TypeScript

npm install typescript@latest @types/react@latest

{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "theme-ui",
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true
  }
}

/** @jsxImportSource theme-ui */

export function Component() {
  return <div sx={{ color: 'primary' }}>Hello</div>
}

import { Interpolation } from '@emotion/react'
import { ThemeUIStyleObject, Theme } from '@theme-ui/css'

export interface SxProp {
  /**
   * The sx prop lets you style elements inline, using values from your
   * theme.
   */
  sx?: ThemeUIStyleObject
  
  /**
   * Theme UI uses Emotion's JSX function. You can pass styles directly
   * using the css prop.
   */
  css?: Interpolation<Theme>
}

import type { ThemeUIStyleObject } from 'theme-ui'

const styles: ThemeUIStyleObject = {
  color: 'primary',
  padding: 3,
  fontSize: [2, 3, 4], // Responsive array
  '&:hover': {
    color: 'secondary',
  },
}

import type { Theme } from 'theme-ui'

const theme: Theme = {
  colors: {
    text: '#000',
    background: '#fff',
    primary: '#0066cc',
  },
  space: [0, 4, 8, 16, 32, 64],
  fonts: {
    body: 'system-ui, sans-serif',
    heading: 'Georgia, serif',
  },
  fontSizes: [12, 14, 16, 20, 24, 32, 48],
}

import type { Theme as ThemeUITheme } from 'theme-ui'

export const theme = {
  colors: {
    text: '#000',
    background: '#fff',
    primary: '#0066cc',
    // Custom colors
    accent: '#ff6b6b',
    success: '#51cf66',
    warning: '#ffd43b',
    danger: '#ff6b6b',
  },
  // Custom button variants
  buttons: {
    primary: { /* ... */ },
    danger: { /* ... */ },
    ghost: { /* ... */ },
  },
} as const

type CustomTheme = typeof theme

// Augment the module
declare module 'theme-ui' {
  interface UserThemes {
    default: CustomTheme
  }
}

export type Theme = CustomTheme

import { theme } from './theme'

// TypeScript knows about 'accent', 'success', etc.
<div sx={{ color: 'accent' }} />

// Autocomplete for custom button variants
<Button variant="ghost" />

import type { Theme as BaseTheme } from 'theme-ui'

interface MyTheme extends BaseTheme {
  colors: {
    text: string
    background: string
    primary: string
    secondary: string
    accent: string
  }
  buttons: {
    primary: object
    secondary: object
    outline: object
  }
}

export const theme: MyTheme = {
  colors: {
    text: '#000',
    background: '#fff',
    primary: '#0066cc',
    secondary: '#cc0066',
    accent: '#ff6b6b',
  },
  buttons: {
    primary: {
      color: 'white',
      bg: 'primary',
    },
    secondary: {
      color: 'white',
      bg: 'secondary',
    },
    outline: {
      color: 'primary',
      bg: 'transparent',
      border: '2px solid',
      borderColor: 'primary',
    },
  },
}

declare module 'theme-ui' {
  interface UserThemes {
    default: MyTheme
  }
}

import { SxProp } from 'theme-ui'

interface CardProps extends SxProp {
  title: string
  children: React.ReactNode
}

export function Card({ title, children, sx }: CardProps) {
  return (
    <div sx={{ padding: 3, borderRadius: 2, ...sx }}>
      <h3>{title}</h3>
      {children}
    </div>
  )
}

// Usage - TypeScript knows about sx prop
<Card title="Hello" sx={{ bg: 'primary' }}>
  Content
</Card>

import { BoxProps } from 'theme-ui'

interface CustomBoxProps extends BoxProps {
  highlight?: boolean
}

export function CustomBox({ highlight, ...props }: CustomBoxProps) {
  return (
    <div
      {...props}
      sx={{
        ...props.sx,
        bg: highlight ? 'accent' : 'background',
      }}
    />
  )
}

import type { ThemedComponent } from '@theme-ui/mdx'

// ThemedComponent accepts sx prop and HTML props
const CustomH1: ThemedComponent<'h1'> = (props) => {
  return <h1 {...props} sx={{ ...props.sx, color: 'primary' }} />
}

import type { ResponsiveStyleValue } from 'theme-ui'

type ResponsiveColor = ResponsiveStyleValue<string>

// All of these are valid
const color1: ResponsiveColor = 'primary'
const color2: ResponsiveColor = ['primary', 'secondary']
const color3: ResponsiveColor = ['primary', null, 'accent'] // null skips breakpoint

import type { Theme } from 'theme-ui'

<div
  sx={{
    // Function receives typed theme
    color: (theme: Theme) => theme.colors?.primary,
    
    // With destructuring
    fontSize: ({ fontSizes }) => fontSizes?.[3],
    
    // Nested functions
    '&:hover': (theme) => ({
      color: theme.colors?.secondary,
    }),
  }}
/>

import type { Scale, ScaleDict } from '@theme-ui/css'

// Array or object scale
type SpaceScale = Scale<number | string>

const space1: SpaceScale = [0, 4, 8, 16, 32]
const space2: SpaceScale = {
  small: 4,
  medium: 8,
  large: 16,
}

import type { ObjectWithDefault } from '@theme-ui/css'

interface ColorScale extends ObjectWithDefault<string> {
  light?: string
  dark?: string
}

const theme = {
  colors: {
    primary: {
      __default: '#0066cc',
      light: '#3399ff',
      dark: '#004080',
    },
  },
}

// Using 'primary' resolves to __default value
<div sx={{ color: 'primary' }} /> // Uses #0066cc
<div sx={{ color: 'primary.light' }} /> // Uses #3399ff

/** @jsxImportSource theme-ui */

// Now sx prop is available
export function Component() {
  return <div sx={{ color: 'primary' }} />
}

import type { Theme } from 'theme-ui'

const theme: Theme = {
  colors: {
    primary: '#0066cc' as const, // Add 'as const' for literal types
  },
}

// Instead of this
const getColor = (name: string, theme: Theme) => theme.colors[name]

// Use this
const getColor = (name: string, theme: Theme) => {
  return theme.colors?.[name as keyof typeof theme.colors]
}

type ButtonVariant = 'primary' | 'secondary' | 'outline'

interface ButtonProps {
  variant?: ButtonVariant
  children: React.ReactNode
}

const buttonStyles: Record<ButtonVariant, ThemeUIStyleObject> = {
  primary: { color: 'white', bg: 'primary' },
  secondary: { color: 'white', bg: 'secondary' },
  outline: { color: 'primary', bg: 'transparent' },
}

export function Button({ variant = 'primary', children }: ButtonProps) {
  return <button sx={buttonStyles[variant]}>{children}</button>
}

import type { ComponentProps, ElementType } from 'react'
import type { SxProp } from 'theme-ui'

interface PolymorphicProps<T extends ElementType> extends SxProp {
  as?: T
}

type Props<T extends ElementType> = PolymorphicProps<T> &
  Omit<ComponentProps<T>, keyof PolymorphicProps<T>>

function ThemedBox<T extends ElementType = 'div'>({
  as,
  sx,
  ...props
}: Props<T>) {
  const Component = as || 'div'
  return <Component sx={{ padding: 3, ...sx }} {...props} />
}

// Usage
<ThemedBox>Div element</ThemedBox>
<ThemedBox as="section">Section element</ThemedBox>
<ThemedBox as="a" href="/">Link element</ThemedBox>

export const theme = {
  colors: {
    modes: {
      dark: {
        text: '#fff',
        background: '#000',
      },
    },
  },
  buttons: {
    primary: {
      color: 'white',
      bg: 'primary',
    },
  },
} as const

type Theme = typeof theme

// Now TypeScript knows the exact structure
declare module 'theme-ui' {
  interface UserThemes {
    default: Theme
  }
}