WidgetControls

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

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.

import { WidgetControls } from "mcp-use/react";

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

React.ReactNode
required
The widget content to wrap. Rendered inside the relatively positioned container, beneath the floating control row.

string
default:"\"\""
Additional CSS classes applied to the wrapper container (which also carries relative h-fit).

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

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.

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.

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.

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

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

object
Current widget props from toolInput.

object
Tool output data (toolOutput).

object
Response metadata (toolResponseMetadata).

object
Persistent widget state (widgetState).

string
Current theme, light or dark.

string
Current display mode: inline, pip, or fullscreen.

string
The user locale.

number
The widget max height, displayed in pixels.

object
Device capabilities, summarized as the device type.

object
Safe area insets for mobile, shown as T B L R values.

boolean
Whether the widget API is available, shown as Yes or No.

string[]
All available keys on the window.openai object, detected after mount.

Actions

action
Test calling another MCP tool. Takes a tool name and a JSON arguments string, then invokes callTool.

action
Send a follow-up message to the conversation via sendFollowUpMessage.

action
Open an external URL via openExternal.

action
Request a display mode (Inline, PiP, or Fullscreen) via requestDisplayMode.

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

button
Shown when viewControls is true or "fullscreen". Calls requestDisplayMode("fullscreen") to expand the widget to fullscreen.

button
Shown when viewControls is true or "pip". Calls requestDisplayMode("pip") to show the widget in a floating window.

Basic Usage

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.

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

import { McpUseProvider } from "mcp-use/react";

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

McpUseProvider: Unified provider that can include WidgetControls.
useWidget: Hook for accessing widget data and actions, used internally by WidgetControls.

Overview

Server

React

Client

Agent

WidgetControls

WidgetControls

debugger overlay

viewControls buttons

Basic Usage

Position Customization

Usage with McpUseProvider

​WidgetControls

​debugger overlay

​viewControls buttons

​Basic Usage

​Position Customization

​Usage with McpUseProvider

​Related

WidgetControls

debugger overlay

viewControls buttons

Basic Usage

Position Customization

Usage with McpUseProvider

Related