# Display modes

Two independent axes control how the widget appears: **mode** (how rooms are presented) and **position** (how it mounts on the page).

## Room modes

Set with `mode`.

### `single` (default)

Locks the embed to one room (`roomId`). No room switcher: ideal for a support widget or a single community room.

```ts
new CherryEmbed({
  appId: 'YOUR_EMBED_ID',
  container: '#cherry-chat',
  roomId: 'YOUR_ROOM_ID',
  mode: 'single',
});
```

> **Warning:** Only `single` is available today. `list` and `external-controlled` (and the `roomChanged` event) are documented ahead of runtime support; selecting them currently behaves like `single`.

### `list`

When available, `list` will render Cherry's room-list UI so the user picks among the rooms they belong to (omit `roomId`). Not wired up yet: currently behaves like `single`.

```ts
new CherryEmbed({
  appId: 'YOUR_EMBED_ID',
  container: '#cherry-chat',
  mode: 'list',
});
```

### `external-controlled`

When available, your app will drive navigation: mount once, then call `setRoom()` whenever your UI changes, e.g. the user opens a different match, order, or channel, and listen for `roomChanged`. Not wired up yet: currently behaves like `single`, and `roomChanged` does not fire.

```ts
const chat = new CherryEmbed({
  appId: 'YOUR_EMBED_ID',
  container: '#cherry-chat',
  mode: 'external-controlled',
});
await chat.mount();

// later: switch rooms from your own UI
chat.setRoom('room_abc123');

chat.on('roomChanged', ({ roomId }) => {
  console.log('active room is now', roomId);
});
```

> **Tip:** Pair `external-controlled` with the [Cherry API](https://portal.cherry.fun/docs/api/rooms.md): create a room on your backend, then call `setRoom(newRoomId)` to drop the user straight into it.

## Position

> **Tip:** Want to see the modes side by side? Toggle floating vs. inline live in the [Cherry embed builder](https://cherry.fun/chat-embed-example/), no signup or backend required.

Set with `position`.

- **`inline`** (default): mounts into your `container` element and flows with your layout.
- **`floating-right` / `floating-left`:** pins the chat panel to a viewport corner. Omit `container`. Use `collapsed: true` to start hidden (the widget doesn't render its own launcher button), and open it from your own UI via `chat.show()` / `chat.toggle()`.

```ts
const chat = new CherryEmbed({
  appId: 'YOUR_EMBED_ID',
  roomId: 'YOUR_ROOM_ID',
  position: 'floating-right',
  collapsed: true,
});
await chat.mount();

// collapsed starts hidden: wire your own button to open it
document.querySelector('#open-chat')?.addEventListener('click', () => chat.toggle());
```

Toggle a floating widget programmatically with `chat.show()`, `chat.hide()`, and `chat.toggle()`.

## Next steps

- [Theming](https://portal.cherry.fun/docs/embed/theming.md) · [SDK API reference](https://portal.cherry.fun/docs/embed/api-reference.md)