mirror of
https://github.com/alpic-ai/skybridge.git
synced 2026-09-14 19:59:55 +08:00
Julien Vallini
0f12579579
Co-authored-by: Frédéric Barthelet <fred@alpic.ai> Co-authored-by: Cursor <cursoragent@cursor.com>
88 lines
3.1 KiB
Plaintext
88 lines
3.1 KiB
Plaintext
---
|
|
title: useDisplayMode
|
|
description: "Read and switch how the host lays out the view"
|
|
---
|
|
|
|
import { Compat } from "/components/compat.jsx";
|
|
|
|
<Compat alpic chatgpt claude goose />
|
|
|
|
A host renders the [view](/build/view) in one of a few layouts: a compact inline panel, fullscreen, or a floating picture-in-picture. `useDisplayMode` lets the view read which layout it is in and ask the host to switch to another.
|
|
|
|
## Example
|
|
|
|
The product carousel shows more columns when it takes the full screen. From the inline panel it offers a "See all" button to expand, and once expanded, a "Collapse" button to shrink back.
|
|
|
|
```tsx highlight={4,10,13,16}
|
|
import { useDisplayMode } from "skybridge/web";
|
|
|
|
function Carousel({ products }: { products: Product[] }) {
|
|
const [mode, setMode] = useDisplayMode();
|
|
|
|
return (
|
|
<div>
|
|
<ProductGrid
|
|
products={products}
|
|
columns={mode === "fullscreen" ? 4 : 2}
|
|
/>
|
|
{mode === "inline" && (
|
|
<button onClick={() => setMode("fullscreen")}>See all {products.length}</button>
|
|
)}
|
|
{mode === "fullscreen" && (
|
|
<button onClick={() => setMode("inline")}>Collapse</button>
|
|
)}
|
|
</div>
|
|
);
|
|
}
|
|
```
|
|
|
|
## Returns
|
|
|
|
`useDisplayMode` returns a tuple: the current mode first, the setter second.
|
|
|
|
### `displayMode`
|
|
|
|
```tsx
|
|
displayMode: DisplayMode;
|
|
```
|
|
|
|
The mode the host is currently rendering the view in. It updates on its own when the host changes the layout (the user expanding or collapsing the view, for instance), so a component can render against it directly.
|
|
|
|
| Mode | Layout | Requestable |
|
|
| --- | --- | :---: |
|
|
| `"inline"` | Compact panel embedded in the conversation, the default | <Icon icon="check" color="#22C55E" /> |
|
|
| `"fullscreen"` | The view takes over the host surface | <Icon icon="check" color="#22C55E" /> |
|
|
| `"pip"` | Picture in picture, floating above the conversation | <Icon icon="check" color="#22C55E" /> |
|
|
| `"modal"` | Overlay opened through [`useRequestModal`](/api-reference/use-request-modal), host-driven | <Icon icon="x" color="#EF4444" /> |
|
|
|
|
### `setDisplayMode`
|
|
|
|
```tsx
|
|
setDisplayMode(mode: RequestDisplayMode): Promise<{ mode: RequestDisplayMode }>;
|
|
```
|
|
|
|
Asks the host to switch the view to `mode`. The host decides: it can grant the request, keep the current mode, or coerce to another. The promise resolves with the mode actually applied, so read the resolved value rather than assuming the request took.
|
|
|
|
**`mode`** the mode to request, every [`DisplayMode`](#displaymode) except `"modal"`:
|
|
|
|
```tsx
|
|
// "inline" | "fullscreen" | "pip"
|
|
type RequestDisplayMode = Exclude<DisplayMode, "modal">;
|
|
```
|
|
|
|
<Info>
|
|
On mobile, **ChatGPT** coerces a `"pip"` request to `"fullscreen"`.
|
|
</Info>
|
|
|
|
<CardGroup cols={3}>
|
|
<Card title="Design for the Host" icon="sparkles" href="/guides/ux">
|
|
Adapt the view to display mode, theme, and device
|
|
</Card>
|
|
<Card title="useViewport" icon="layout" href="/api-reference/use-viewport">
|
|
Read the space and insets a mode switch brings
|
|
</Card>
|
|
<Card title="useRequestModal" icon="app-window" href="/api-reference/use-request-modal">
|
|
Open the view as a host modal
|
|
</Card>
|
|
</CardGroup>
|