Skip to main content

​
WidgetControls

The WidgetControls component adds control buttons for widget debugging and view controls (fullscreen/pip). It combines debug button and view controls with shared hover logic, making it easy to add development and testing capabilities to your widgets.

​
Import

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

​
Props

PropTypeDefaultDescription
childrenReact.ReactNoderequiredThe widget content to wrap
debuggerbooleanfalseEnable debug button to display widget debug information
viewControlsboolean | "pip" | "fullscreen"falseEnable view controls. true = both pip and fullscreen, "pip" = only pip, "fullscreen" = only fullscreen
position"top-left" | "top-center" | "top-right" | "center-left" | "center-right" | "bottom-left" | "bottom-center" | "bottom-right""top-right"Position of the control buttons
attachToHTMLElement | nullundefinedElement to attach controls to (for custom positioning)
showLabelsbooleantrueShow labels on control buttons
classNamestring""Additional CSS classes

​
Basic Usage

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

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

​
Debug Button

The debug button opens an overlay showing:
  • Props: Current widget props from toolInput
  • Output: Tool output data (toolOutput)
  • Metadata: Response metadata (toolResponseMetadata)
  • State: Persistent widget state (widgetState)
  • Theme: Current theme (light/dark)
  • Display Mode: Current display mode (inline/pip/fullscreen)
  • Safe Area: Safe area insets for mobile
  • User Agent: Device capabilities
  • Locale: User locale
  • window.openai Keys: All available keys on the window.openai object
The debug overlay also includes interactive testing:
  • Call Tool: Test calling other MCP tools
  • Send Follow-up Message: Send messages to ChatGPT conversation
  • Open External: Test opening external URLs
  • Set State: Update widget state

​
View Controls

View controls allow users to change the widget’s display mode:
  • Fullscreen Button: Expands widget to fullscreen mode
  • Picture-in-Picture Button: Shows widget in a floating window
These controls automatically appear/disappear based on the current display mode and availability.

​
Position Customization

Control buttons can be positioned in 8 different locations: 
// 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>

​
Hover Behavior

All control buttons share the same hover logic:
  • Hidden by default: Controls are invisible (opacity-0) until hovered
  • Show on hover: Controls become visible (opacity-100) when hovering over the widget
  • Smooth transition: 200ms transition for smooth appearance/disappearance
This keeps the UI clean while making controls easily accessible when needed.

​
Dev Mode Detection

When running in the inspector’s dev widget proxy (/inspector/api/dev-widget/), the controls are automatically hidden since the inspector provides its own debugging interface. This prevents duplicate controls.

​
Usage with McpUseProvider

WidgetControls is automatically included when using McpUseProvider with the debugger or viewControls props: 
import { McpUseProvider } from 'mcp-use/react';

<McpUseProvider debugger viewControls>
  <MyWidget />
</McpUseProvider>
This is the recommended approach as it also includes other necessary providers.

​
Standalone Usage

You can also use WidgetControls standalone if you’re managing other providers yourself: 
import { WidgetControls } from 'mcp-use/react';
import { ThemeProvider } from 'mcp-use/react';

<ThemeProvider>
  <WidgetControls debugger viewControls position="top-left">
    <MyWidget />
  </WidgetControls>
</ThemeProvider>
  • McpUseProvider - Unified provider that includes WidgetControls
  • useWidget - Hook for accessing widget data and actions