---
title: "<WidgetControls />"
description: "Wrapper component that adds control buttons for widget debugging and view controls"
icon: "settings"
---

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.

<Tip>
  You can use `<McpUseProvider viewControls />` to automatically include the `<WidgetControls />` component.
</Tip>

## Import

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

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `React.ReactNode` | **required** | The widget content to wrap |
| `debugger` | `boolean` | `false` | Enable debug button to display widget debug information |
| `viewControls` | `boolean \| "pip" \| "fullscreen"` | `false` | Enable 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 |
| `attachTo` | `HTMLElement \| null` | `undefined` | Element to attach controls to (for custom positioning) |
| `showLabels` | `boolean` | `true` | Show labels on control buttons |
| `className` | `string` | `""` | Additional CSS classes |

## Basic Usage

```tsx
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:

```tsx
// 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 automatically included when using `McpUseProvider` with the `debugger` or `viewControls` props:

```tsx
import { McpUseProvider } from 'mcp-use/react';

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

This is the recommended approach as it also includes other necessary providers.

## Related Components

- [`McpUseProvider`](./mcpuseprovider) - Unified provider that includes WidgetControls
- [`useWidget`](./usewidget) - Hook for accessing widget data and actions

