> ## 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.

# WidgetControls

> Wrapper component that adds control buttons for widget debugging and view controls

**Source Code**

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

## WidgetControls

Wrapper component that adds control buttons for widget debugging and view controls (fullscreen and picture-in-picture). It combines a debug button and view controls under shared hover logic, so you can drop development and testing capabilities onto any widget by wrapping its content.

```tsx theme={null}
import { WidgetControls } from "mcp-use/react";
```

> [!TIP]
>
> Use `<McpUseProvider debugger viewControls />` to automatically include `WidgetControls`. That is the recommended approach since the provider also wires up the other providers a widget needs.

Wraps `children` in a relatively positioned container and overlays a row of icon buttons. All buttons share the same hover logic and render together. The control row fades in on hover (`opacity-100` / `pointer-events-auto`) and fades out otherwise (`opacity-0` / `pointer-events-none`).

The component reads live widget data and actions from the `useWidget()` hook (props, output, metadata, state, theme, display mode, safe area, max height, locale, user agent, availability, and the `callTool`, `sendFollowUpMessage`, `openExternal`, `requestDisplayMode`, and `setState` actions). When rendered inside the inspector (detected when `window.location.pathname` includes `/inspector/api/`) all controls are hidden, because the inspector renders its own controls.

**Props**

> **children** `React.ReactNode` *required*
>
> The widget content to wrap. Rendered inside the relatively positioned container, beneath the floating control row.
>
> **className** `string` (default: "")
>
> Additional CSS classes applied to the wrapper container (which also carries `relative h-fit`).
>
> **position** `"top-left" | "top-center" | "top-right" | "center-left" | "center-right" | "bottom-left" | "bottom-center" | "bottom-right"` (default: "top-right")
>
> Where the control buttons are placed within the wrapper. One of eight positions. Drives both the Tailwind position classes and the safe-area-aware inline offsets.
>
> **attachTo** `HTMLElement | null` (default: undefined)
>
> When provided, hover detection is bound to this element via `mouseenter` / `mouseleave` listeners instead of the wrapper. Use it to reveal the controls from a custom element. When set, the wrapper's own hover handlers are skipped.
>
> **showLabels** `boolean` (default: true)
>
> Whether each button shows a hover tooltip with its label (for example "Fullscreen", "Picture in Picture", "Debug Info"). The tooltip position adapts to the `position` prop.
>
> **debugger** `boolean` (default: false)
>
> Enables the debug button. When `true`, a debug icon appears that toggles a full-screen overlay showing widget debug info and interactive action controls.
>
> **viewControls** `boolean | "pip" | "fullscreen"` (default: false)
>
> Enables the view controls. `true` shows both the picture-in-picture and fullscreen buttons, `"pip"` shows only the picture-in-picture button, and `"fullscreen"` shows only the fullscreen button. View control buttons are hidden while the widget is already in `fullscreen` or `pip` display mode.

**Signature**

```ts wrap theme={null}
function WidgetControls({ children, className = "", position = "top-right", attachTo, showLabels = true, debugger: enableDebugger = false, viewControls = false }: WidgetControlsProps): JSX.Element
```

### debugger overlay

When `debugger` is `true`, the debug button toggles a fixed full-screen overlay (`z-[10000]`). The overlay closes on a backdrop click, on a click outside its content, and via an explicit close button, and it locks `document.body` scroll while open.

**Debug Info table**

> **Props** `object`
>
> Current widget props from `toolInput`.
>
> **Output** `object`
>
> Tool output data (`toolOutput`).
>
> **Metadata** `object`
>
> Response metadata (`toolResponseMetadata`).
>
> **State** `object`
>
> Persistent widget state (`widgetState`).
>
> **Theme** `string`
>
> Current theme, light or dark.
>
> **Display Mode** `string`
>
> Current display mode: inline, pip, or fullscreen.
>
> **Locale** `string`
>
> The user locale.
>
> **Max Height** `number`
>
> The widget max height, displayed in pixels.
>
> **User Agent** `object`
>
> Device capabilities, summarized as the device type.
>
> **Safe Area** `object`
>
> Safe area insets for mobile, shown as `T B L R` values.
>
> **API Available** `boolean`
>
> Whether the widget API is available, shown as Yes or No.
>
> **window\.openai Keys** `string[]`
>
> All available keys on the `window.openai` object, detected after mount.

**Actions**

> **Call Tool** `action`
>
> Test calling another MCP tool. Takes a tool name and a JSON arguments string, then invokes `callTool`.
>
> **Send Follow-Up** `action`
>
> Send a follow-up message to the conversation via `sendFollowUpMessage`.
>
> **Open Link** `action`
>
> Open an external URL via `openExternal`.
>
> **Display Mode** `action`
>
> Request a display mode (Inline, PiP, or Fullscreen) via `requestDisplayMode`.
>
> **Set State** `action`
>
> Update widget state via `setState` (adds a `debugTimestamp` to the current state).

### viewControls buttons

When `viewControls` is enabled, the control row shows view-mode buttons. They are only visible while the widget is not already in `fullscreen` or `pip` display mode.

**Buttons**

> **Fullscreen** `button`
>
> Shown when `viewControls` is `true` or `"fullscreen"`. Calls `requestDisplayMode("fullscreen")` to expand the widget to fullscreen.
>
> **Picture in Picture** `button`
>
> Shown when `viewControls` is `true` or `"pip"`. Calls `requestDisplayMode("pip")` to show the widget in a floating window.

## Basic Usage

```tsx wrap theme={null}
import { WidgetControls } from "mcp-use/react";

function MyWidget() {
  return (
    <WidgetControls debugger viewControls>
      <div>My widget content</div>
    </WidgetControls>
  );
}
```

## Position Customization

Control buttons can be placed in any of the eight positions. The placement also reflows the hover tooltip and applies safe-area-aware offsets.

```tsx wrap theme={null}
// Top right (default)
<WidgetControls position="top-right" debugger>
  <MyWidget />
</WidgetControls>

// Bottom left
<WidgetControls position="bottom-left" debugger>
  <MyWidget />
</WidgetControls>

// Center right
<WidgetControls position="center-right" debugger>
  <MyWidget />
</WidgetControls>
```

## Usage with McpUseProvider

`WidgetControls` is included automatically when you pass `debugger` or `viewControls` to `McpUseProvider`. This is the recommended approach since the provider also sets up the other providers a widget needs.

```tsx wrap theme={null}
import { McpUseProvider } from "mcp-use/react";

<McpUseProvider debugger viewControls>
  <MyWidget />
</McpUseProvider>
```

## Related

* [McpUseProvider](https://docs.mcp-use.com/v1/typescript/api-reference/react/mcpuseprovider.md): Unified provider that can include `WidgetControls`.
* [useWidget](https://docs.mcp-use.com/v1/typescript/api-reference/react/usewidget.md): Hook for accessing widget data and actions, used internally by `WidgetControls`.


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