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

# Widget Types

> Choose between tray, full-screen, and chatbar layouts for your embedded agent.

The embed widget ships with three layout types. Each is optimized for a different use case. Set the type when calling `embedWidget()`:

```javascript theme={null}
const widget = embedWidget({
  url: 'https://console.thesys.dev/app/your-slug',
  type: 'tray', // 'tray' | 'full-screen' | 'chatbar'
});
```

***

## Tray

```javascript theme={null}
embedWidget({ url: '...', type: 'tray' });
```

The default layout. A floating circular button appears in the **bottom-right corner**. Clicking it opens a compact chat panel (583 × 800px, capped at `100vh - 100px`).

**Best for:** Help widgets, customer support, contextual assistants that shouldn't dominate the page.

<Tip>
  On mobile devices (viewport under 768px), the tray automatically switches to a full-screen layout for better usability. See [Mobile Behavior](/agent-builder/embed-widget/mobile-behavior).
</Tip>

***

## Full-screen

```javascript theme={null}
embedWidget({ url: '...', type: 'full-screen' });
```

Same floating button as the tray, but clicking it opens the agent as a **full-screen overlay**. The agent fills the entire viewport.

**Best for:** Dedicated AI assistant pages, onboarding flows, or experiences where you want the agent to be the primary focus.

***

## Chatbar

```javascript theme={null}
embedWidget({ url: '...', type: 'chatbar' });
```

An **inline input bar** fixed to the bottom center of the page — no floating button. The user types directly into the bar, and a chat window opens above it.

**Best for:** Search-like experiences, landing pages, AI-native products where the agent is the main interaction point.

### Chatbar-Specific Options

The chatbar type accepts additional configuration through the `options` property:

```javascript theme={null}
embedWidget({
  url: 'https://console.thesys.dev/app/your-slug',
  type: 'chatbar',
  options: {
    placeholder: 'Ask me anything about our product...',
    keyboardShortcutEnabled: true,
    conversationStarters: [
      'What can you help me with?',
      'Show me pricing plans',
      'How do I get started?',
    ],
  },
});
```

| Option                    | Type           | Default             | Description                                                                                      |
| ------------------------- | -------------- | ------------------- | ------------------------------------------------------------------------------------------------ |
| `placeholder`             | `string`       | `"Ask me anything"` | Placeholder text in the input field                                                              |
| `keyboardShortcutEnabled` | `boolean`      | `true`              | Press **Space** anywhere on the page to focus the input (only when no other input is focused)    |
| `conversationStarters`    | `string[]`     | `[]`                | Suggested prompts displayed above the input when focused                                         |
| `theme`                   | `ChatbarTheme` | —                   | Visual overrides for the chatbar. See [Customization](/agent-builder/embed-widget/customization) |

### Keyboard Shortcuts

When `keyboardShortcutEnabled` is `true` (the default):

* **Space** — Focuses the chatbar input (only when no other text field is active)
* **Escape** — Blurs the chatbar input

### Conversation Starters

When the input is focused and the chat window is closed, the starters appear as clickable chips labeled **A**, **B**, **C**, etc. Clicking one sends it as the first message and opens the chat window.

***

## Choosing a Type

| Criteria         | Tray            | Full-screen      | Chatbar                              |
| ---------------- | --------------- | ---------------- | ------------------------------------ |
| Presence on page | Floating button | Floating button  | Inline input bar                     |
| Space when open  | Compact panel   | Full viewport    | Window above input                   |
| Best for         | Help / support  | Focused AI tasks | Search / main UX                     |
| Mobile behavior  | Full-screen     | Full-screen      | Input stays; window goes full-screen |