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

# MCP Apps requestDisplayMode - Change Display Mode

> Request the host to change the MCP App display mode between inline, fullscreen, and picture-in-picture (pip). The host returns the mode actually set.

<Badge color="green">MCP Apps SDK</Badge>

```ts theme={null}
import { App } from "@modelcontextprotocol/ext-apps";
```

## Overview

`requestDisplayMode` asks the host to change how the MCP App View is displayed. The three possible display modes are:

* **`"inline"`** -- The default mode. The View is rendered inline within the chat conversation.
* **`"fullscreen"`** -- The View expands to fill the host's available space.
* **`"pip"`** -- Picture-in-picture mode. The View floats in a small overlay window.

These values are defined by the `McpUiDisplayMode` type. See [Core Types](/mcp-apps/types/core-types) for the full type definition.

The host may not support all display modes. The returned `mode` reflects what was actually set, which may differ from the requested mode if the host does not support it. Always check the host context's `availableDisplayModes` before requesting a mode change, and use the returned value to update your UI state.

## Signature

```ts theme={null}
async requestDisplayMode(
  params: { mode: McpUiDisplayMode },
  options?: RequestOptions,
): Promise<{ mode: McpUiDisplayMode }>
```

## Parameters

<ResponseField name="params" type="object" required>
  <ResponseField name="mode" type="McpUiDisplayMode" required>
    The desired display mode. One of `"inline"`, `"fullscreen"`, or `"pip"`.
  </ResponseField>
</ResponseField>

<ResponseField name="options" type="RequestOptions">
  Optional request configuration such as timeout or abort signal.
</ResponseField>

## Returns

<ResponseField name="result" type="object">
  <ResponseField name="mode" type="McpUiDisplayMode">
    The display mode actually set by the host. This may differ from the requested mode if the host does not support it.
  </ResponseField>
</ResponseField>

## Usage

### Toggling between inline and fullscreen

```ts theme={null}
const ctx = app.getHostContext();
const newMode = ctx?.displayMode === "inline" ? "fullscreen" : "inline";

if (ctx?.availableDisplayModes?.includes(newMode)) {
  const result = await app.requestDisplayMode({ mode: newMode });
  container.classList.toggle("fullscreen", result.mode === "fullscreen");
}
```

### Entering picture-in-picture mode

```ts theme={null}
const ctx = app.getHostContext();

if (ctx?.availableDisplayModes?.includes("pip")) {
  const result = await app.requestDisplayMode({ mode: "pip" });
  if (result.mode === "pip") {
    showMinimalUI();
  }
}
```

### Handling unsupported modes gracefully

```ts theme={null}
async function setDisplayMode(desired: McpUiDisplayMode) {
  const ctx = app.getHostContext();

  if (!ctx?.availableDisplayModes?.includes(desired)) {
    console.warn(`Display mode "${desired}" is not available on this host`);
    return;
  }

  const result = await app.requestDisplayMode({ mode: desired });

  if (result.mode !== desired) {
    console.warn(`Requested "${desired}" but host set "${result.mode}"`);
  }

  updateLayout(result.mode);
}
```

### Building a mode switcher

```ts theme={null}
const ctx = app.getHostContext();
const modes: McpUiDisplayMode[] = ["inline", "fullscreen", "pip"];

for (const mode of modes) {
  const button = document.createElement("button");
  button.textContent = mode;
  button.disabled = !ctx?.availableDisplayModes?.includes(mode);
  button.addEventListener("click", async () => {
    const result = await app.requestDisplayMode({ mode });
    updateActiveButton(result.mode);
  });
  toolbar.appendChild(button);
}
```

## Related

* [`useRequestDisplayMode`](/app-framework/hooks/use-request-display-mode) -- React hook that wraps this method.
* [Core Types](/mcp-apps/types/core-types) -- Full definition of `McpUiDisplayMode`.
* [`getHostContext()`](/mcp-apps/app/accessors/get-host-context) -- returns the current display mode and available modes.
* [Event Handlers](/mcp-apps/app/event-handlers) -- Listen for host-initiated display mode changes.