> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mcp-use.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ThemeProvider

> Theme provider component that manages dark mode and host style variables for widgets API Documentation

**Source Code**

View the source code for this module on GitHub: [[https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/mcp-use/src/react/ThemeProvider.tsx](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/mcp-use/src/react/ThemeProvider.tsx)](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/mcp-use/src/react/ThemeProvider.tsx)

`ThemeProvider` manages dark mode by setting the `dark` class and `data-theme` attribute on the document root element (`document.documentElement`). It resolves the active theme from the MCP Apps host context, falling back to the operating system preference when the host does not supply a theme. It also applies host style variables so CSS that uses `light-dark()` resolves against the active host theme.

## ThemeProvider

Component that manages the dark mode class on the document root and synchronizes host style variables.

```tsx theme={null}
import { ThemeProvider } from 'mcp-use/react'
```

Wraps widget content and applies the active theme to `document.documentElement`. On render and whenever the effective theme changes, it removes the `light` and `dark` classes from the root element, then adds the active one, sets the `data-theme` attribute to `"light"` or `"dark"`, and (when enabled) sets `document.documentElement.style.colorScheme`. It also calls `applyHostStyleVariables` with the host context style variables so host design tokens are available as CSS variables.

The effective theme is computed with the following priority:

1. **Explicit host context theme.** When the MCP Apps host context reports a theme of `"dark"` or `"light"`, that value is used. The component reads the raw host context (not the value normalized by `useWidget`, which defaults a missing theme to `"light"`), so an omitted host theme is not treated as an explicit light-mode preference.
2. **System preference.** When the host does not provide `"dark"` or `"light"`, the component falls back to the `prefers-color-scheme: dark` media query. During server-side rendering (when `window` is `undefined`) the initial system preference is `"light"`.

The component subscribes to the `prefers-color-scheme: dark` media query and re-renders when the system theme changes, removing the listener on unmount. Theme application runs inside `useLayoutEffect`, so it executes synchronously before browser paint to prevent a flash of the wrong theme.

The component renders its `children` directly inside a React fragment and adds no wrapper element to the DOM.

> [!TIP]
>
> `McpUseProvider` includes `ThemeProvider` automatically, so most widgets do not need to render `ThemeProvider` themselves.

**Props**

> **children** `React.ReactNode` *required*
>
> The widget content to wrap. Rendered as-is inside a fragment.
>
> **colorScheme** `boolean` (default: true)
>
> When `true` (the default), sets `document.documentElement.style.colorScheme` to the active theme (`"light"` or `"dark"`). When `false`, clears the inline `colorScheme` style by setting it to an empty string.

**Signature**

```tsx wrap theme={null}
const ThemeProvider: React.FC<{ children: React.ReactNode; colorScheme?: boolean }>
```

## Side effects

`ThemeProvider` mutates the document root and registers a media query listener. The following table documents every observable effect.

**document.documentElement classList** `light | dark`

The `light` and `dark` classes are both removed, then the class matching the effective theme is added. This drives Tailwind dark mode.

**document.documentElement data-theme** `light | dark`

Set to the effective theme. This drives UI design tokens that key off `data-theme`.

**document.documentElement.style.colorScheme** `light | dark | empty string`

Set to the effective theme when `colorScheme` is `true`, otherwise cleared to an empty string. Setting `color-scheme` lets host variables that use CSS `light-dark()` resolve against the active host theme.

**host style variables** `CSS custom properties`

`applyHostStyleVariables` is called with the host context style variables (`hostContext.styles.variables`) whenever the host context changes, applying host design tokens as CSS variables.

## Basic Usage

```tsx theme={null}
import { ThemeProvider } from 'mcp-use/react'

function MyWidget() {
  return (
    <ThemeProvider>
      <div>My widget content</div>
    </ThemeProvider>
  )
}
```

Disable the inline `color-scheme` style by passing `colorScheme={false}`:

```tsx theme={null}
import { ThemeProvider } from 'mcp-use/react'

function MyWidget() {
  return (
    <ThemeProvider colorScheme={false}>
      <div>My widget content</div>
    </ThemeProvider>
  )
}
```

## Related

* [`McpUseProvider`](https://docs.mcp-use.com/v1/typescript/api-reference/react/mcpuseprovider) includes `ThemeProvider` automatically.
* [`useWidget`](https://docs.mcp-use.com/v1/typescript/api-reference/react/usewidget) exposes the host context theme and other widget data.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.