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

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://mcp-use.com/docs/feedback

```json
{
  "path": "/typescript/server/widget-components/widgetcontrols",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# <WidgetControls />

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

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 theme={null}
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 theme={null}
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 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 automatically included when using `McpUseProvider` with the `debugger` or `viewControls` props:

```tsx theme={null}
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