> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/system-ui/theme-ui/llms.txt
> Use this file to discover all available pages before exploring further.
# @theme-ui/theme-provider
> Complete ThemeUIProvider with color modes and root styles
The `@theme-ui/theme-provider` package provides the full-featured `ThemeUIProvider` component that combines the core theme provider with color mode support and root styles.
## Installation
```bash theme={null}
npm install @theme-ui/theme-provider @emotion/react
```
This package is included in the main `theme-ui` package. You typically don't need to install it separately. The main `theme-ui` package re-exports `ThemeUIProvider`.
## When to Use
This package is primarily for internal use. You would only install it directly if you're:
* Building a custom Theme UI configuration
* Using specific Theme UI packages without the umbrella package
* Need the provider without other Theme UI utilities
For most projects, use the `theme-ui` package which includes this provider:
```jsx theme={null}
import { ThemeUIProvider } from 'theme-ui'
```
## Exports
### Components
#### `ThemeUIProvider`
The main provider component that sets up Theme UI for your application.
```jsx theme={null}
import { ThemeUIProvider } from '@theme-ui/theme-provider'
import theme from './theme'
function App({ children }) {
return (
{children}
)
}
```
**Props:**
* `theme`: `Theme` - Your theme object
* `children`: `React.ReactNode` - Child components
**Features:**
* Provides theme context to all child components
* Enables color mode functionality
* Applies root styles to `` and ``
* Sets up CSS custom properties
* Configures border-box box-sizing by default
#### `ThemeProvider` (deprecated)
A deprecated alias for `ThemeUIProvider`.
```jsx theme={null}
// Deprecated - use ThemeUIProvider instead
import { ThemeProvider } from '@theme-ui/theme-provider'
```
`ThemeProvider` is deprecated to avoid confusion with Emotion's ThemeProvider. Use `ThemeUIProvider` instead. The `ThemeProvider` export will be removed in a future version.
## What It Does
The `ThemeUIProvider` combines several features:
### 1. Core Theme Provider
Provides theme context from `@theme-ui/core`:
```jsx theme={null}
// Internally uses:
import { ThemeProvider as CoreProvider } from '@theme-ui/core'
```
### 2. Color Mode Support
Adds color mode functionality from `@theme-ui/color-modes`:
```jsx theme={null}
// Internally includes:
import { ColorModeProvider } from '@theme-ui/color-modes'
```
### 3. Root Styles
Applies global root styles to your application:
```jsx theme={null}
// Applies these styles:
{
'*': {
boxSizing: 'border-box', // Can be disabled
},
html: {
variant: 'styles.root', // Uses theme.styles.root
},
body: {
margin: 0,
},
}
```
## Usage
### Basic Setup
```jsx theme={null}
import { ThemeUIProvider } from '@theme-ui/theme-provider'
const theme = {
colors: {
text: '#000',
background: '#fff',
primary: '#07c',
},
fonts: {
body: 'system-ui, sans-serif',
heading: 'Georgia, serif',
},
}
function App() {
return (
)
}
```
### With Root Styles
```jsx theme={null}
const theme = {
styles: {
root: {
fontFamily: 'body',
lineHeight: 'body',
fontWeight: 'body',
},
},
}
```
### With Color Modes
```jsx theme={null}
const theme = {
colors: {
text: '#000',
background: '#fff',
primary: '#07c',
modes: {
dark: {
text: '#fff',
background: '#000',
primary: '#0cf',
},
},
},
}
```
### Nested Providers
You can nest providers to override theme values in specific sections:
```jsx theme={null}
```
## Configuration
Configure provider behavior in your theme:
```javascript theme={null}
const theme = {
config: {
// Use CSS custom properties for theme values
useCustomProperties: true,
// Apply border-box to all elements
useBorderBox: true,
// Apply root styles to
useRootStyles: true,
// Color mode settings
initialColorModeName: 'light',
useColorSchemeMediaQuery: true,
useLocalStorage: true,
},
}
```
### Configuration Options
#### `useCustomProperties`
**Type:** `boolean`\
**Default:** `true`
Generate CSS custom properties for theme values:
```javascript theme={null}
// When true, generates:
:root {
--theme-ui-colors-primary: #07c;
--theme-ui-colors-text: #000;
}
```
#### `useBorderBox`
**Type:** `boolean`\
**Default:** `true`
Apply `box-sizing: border-box` to all elements:
```javascript theme={null}
// When true, applies:
* {
box-sizing: border-box;
}
```
#### `useRootStyles`
**Type:** `boolean`\
**Default:** `true`
Apply `theme.styles.root` to the `` element:
```javascript theme={null}
// When true and theme.styles.root exists:
html {
// styles from theme.styles.root
}
```
#### Color Mode Options
See [@theme-ui/color-modes](/api/packages/color-modes) for color mode configuration.
## Implementation Details
### Root Styles Logic
Root styles are only applied:
* On the top-level provider (not nested providers)
* When `useRootStyles` is not `false`
* When `theme.styles.root` exists (for root variant)
### Multiple Versions Warning
If multiple versions of `@emotion/react` are detected, a warning is logged in development mode.
## Dependencies
The package depends on:
```json theme={null}
{
"dependencies": {
"@theme-ui/color-modes": "workspace:^",
"@theme-ui/core": "workspace:^",
"@theme-ui/css": "workspace:^"
},
"peerDependencies": {
"@emotion/react": "^11.13.3",
"react": ">=18"
}
}
```
## TypeScript Types
```typescript theme={null}
import type { ThemeProviderProps } from '@theme-ui/theme-provider'
interface ThemeProviderProps {
theme: Theme
children?: React.ReactNode
}
```
## Notes
* This is primarily an internal package
* Most users should import from `theme-ui` instead
* Combines core provider, color modes, and root styles
* Requires React 18 or higher
* Requires `@emotion/react` as a peer dependency
* No side effects - safe for tree-shaking
## Related
* [@theme-ui/core](/api/packages/core) - Core theme provider without extras
* [@theme-ui/color-modes](/api/packages/color-modes) - Color mode utilities
* [theme-ui](/api/theme-ui) - Main package documentation
* [Getting Started](/getting-started) - Setup guide