useThemeUI

The useThemeUI hook provides access to the Theme UI context, including the current theme and color mode functions.

Import

import { useThemeUI } from 'theme-ui'

Signature

function useThemeUI(): ThemeUIContextValue

Return Value

ThemeUIContextValue

The Theme UI context object

Theme

The current theme object with all merged values

string

The current color mode (e.g., ‘default’, ‘dark’). Available when using ThemeUIProvider.

(mode: string) => void

Function to change the current color mode. Available when using ThemeUIProvider.

string

Internal version string for Emotion compatibility checking

Usage

Accessing Theme Values

import { useThemeUI } from 'theme-ui'

function Component() {
  const { theme } = useThemeUI()
  
  return (
    <div>
      <p>Primary color: {theme.colors?.primary}</p>
      <p>Body font: {theme.fonts?.body}</p>
    </div>
  )
}

Accessing Color Mode

import { useThemeUI } from 'theme-ui'

function DarkModeToggle() {
  const { colorMode, setColorMode } = useThemeUI()
  
  return (
    <button
      onClick={() => {
        setColorMode?.(colorMode === 'default' ? 'dark' : 'default')
      }}
    >
      {colorMode === 'dark' ? 'Light' : 'Dark'} Mode
    </button>
  )
}

Reading Nested Theme Values

import { useThemeUI } from 'theme-ui'

function Component() {
  const { theme } = useThemeUI()
  
  // Access nested scale values
  const spacing = theme.space?.[3]
  const fontSize = theme.fontSizes?.[2]
  const buttonVariant = theme.buttons?.primary
  
  return (
    <div style={{ padding: spacing, fontSize }}>
      Content
    </div>
  )
}

Using with TypeScript

The hook is fully typed and will provide autocomplete for your theme:

import { useThemeUI } from 'theme-ui'

function Component() {
  const context = useThemeUI()
  
  // TypeScript knows the shape of your theme
  const primary: string | undefined = context.theme.colors?.primary
  const colorMode: string = context.colorMode || 'default'
  
  return <div>Component</div>
}

Example: Theme-Aware Component

import { useThemeUI } from 'theme-ui'

function ThemedButton({ children }: { children: React.ReactNode }) {
  const { theme } = useThemeUI()
  
  return (
    <button
      style={{
        backgroundColor: theme.colors?.primary,
        color: theme.colors?.background,
        padding: `${theme.space?.[2]}px ${theme.space?.[3]}px`,
        borderRadius: theme.radii?.[1],
        fontFamily: theme.fonts?.body,
      }}
    >
      {children}
    </button>
  )
}

Example: Using in Tests

import { renderJSON } from '@theme-ui/test-utils'
import { ThemeProvider, useThemeUI } from '@theme-ui/core'

test('returns theme context', () => {
  let context: ThemeUIContextValue | undefined
  
  const GetContext = () => {
    context = useThemeUI()
    return null
  }
  
  renderJSON(
    <ThemeProvider
      theme={{
        colors: {
          text: 'tomato',
        },
      }}
    >
      <GetContext />
    </ThemeProvider>
  )
  
  expect(context).toBeTruthy()
  expect(context?.theme.colors?.text).toBe('tomato')
})

Notes

This hook must be used within a ThemeUIProvider or ThemeProvider component
The colorMode and setColorMode properties are only available when using ThemeUIProvider (not the core ThemeProvider)
The returned theme object is the fully merged theme, including any nested provider themes

ThemeUIProvider - Root theme provider component
Theme Specification - Theme object structure
Color Modes - Working with color modes

Core

Styling

Color Modes

Components

Packages

Import

Signature

Return Value

Usage

Accessing Theme Values

Accessing Color Mode

Reading Nested Theme Values

Using with TypeScript

Example: Theme-Aware Component

Example: Using in Tests

Notes

​Import

​Signature

​Return Value

​Usage

​Accessing Theme Values

​Accessing Color Mode

​Reading Nested Theme Values

​Using with TypeScript

​Example: Theme-Aware Component

​Example: Using in Tests

​Notes

​Related

Import

Signature

Return Value

Usage

Accessing Theme Values

Accessing Color Mode

Reading Nested Theme Values

Using with TypeScript

Example: Theme-Aware Component

Example: Using in Tests

Notes

Related