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

# Copilot UI Components

> Embed the full ChatATP Copilot directly into your web applications

The `@chatatp/studio` SDK goes beyond a simple HTTP wrapper—it provides fully managed, plug-and-play UI components to embed the ChatATP Copilot directly into your web applications.

The components handle the complete conversational lifecycle, streaming state, markdown rendering, tool execution, and rich animations out of the box, allowing you to focus on your app's core features.

We support multiple frameworks via dedicated subpath exports.

## Available Wrappers

### React

The `/react` subpath provides a native React component.

```tsx theme={null}
import { Copilot } from "@chatatp/studio/react";

function App() {
  return (
    <div>
      <header>
        {/* Place the button anywhere in your app */}
        <Copilot 
          apiKey="YOUR_API_KEY"
          agentId={7}
          userId="user_123"
          userDisplayName="John Doe"
          mode="sidebar" 
          position="right"
          themePrimary="blue"
          themeSecondary="orange"
          themeMode="light"
          placeholder="Ask me anything..."
          statusText="Ask anything about your agents."
          inputPlaceholder="Ask your agent..."
          emptyHeading="What are we building today?"
          emptySubheading="Choose a starter or ask freely."
          fullscreenUrl="/copilot"
          quickActions={[
            { icon: <Bot size={16} />, title: "Build an Agent", subtitle: "Start from scratch", prompt: "Help me build an agent" },
            { iconHtml: "<svg>...</svg>", title: "Connect Tools", subtitle: "APIs and integrations", prompt: "Help me connect tools" }
          ]}
        />
      </header>
    </div>
  );
}
```

### Vue

The `/vue` subpath provides a native Vue component.

```vue theme={null}
<script setup>
import { Copilot } from '@chatatp/studio/vue';
</script>

<template>
  <Copilot 
    apiKey="YOUR_API_KEY"
    agentId="7"
    mode="popup"
    position="right"
  />
</template>
```

### Angular

Import `CopilotDirective` from `@chatatp/studio/angular` and use it on an element or as a standalone component.

### Vanilla Web Components

You can also use the core Web Components directly in vanilla HTML or any other framework that supports Custom Elements.

```html theme={null}
<script type="module">
  import '@chatatp/studio/web';
</script>

<chatatp-copilot-button
  apiKey="YOUR_API_KEY"
  agentId="7"
  mode="fullscreen"
  fullscreen-url="/copilot"
></chatatp-copilot-button>
```

## Customization Options

All wrappers expose the following properties for customization:

| Property                                 | Type                                   | Default                                                 | Description                                                                                                              |
| ---------------------------------------- | -------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `apiKey`                                 | string                                 | **Required**                                            | Your ChatATP API Key                                                                                                     |
| `agentId`                                | string/number                          | **Required**                                            | The ID of the agent to connect to                                                                                        |
| `userId`                                 | string                                 | `'anonymous'`                                           | External ID for tracking users                                                                                           |
| `userDisplayName`                        | string                                 | `'User'`                                                | Display name shown in chats                                                                                              |
| `mode`                                   | `'popup' \| 'sidebar' \| 'fullscreen'` | `'popup'`                                               | The layout style of the opened chat window                                                                               |
| `position`                               | `'left' \| 'right'`                    | `'right'`                                               | Which side the chat window aligns to                                                                                     |
| `themePrimary`                           | string                                 | `'#0ea5e9'`                                             | Primary action/doodle color for avatar, user bubbles, send button, focus states; accepts hex, rgb, or common color names |
| `themeSecondary`                         | string                                 | `'#6366f1'`                                             | Secondary surface/background color for panels, containers, assistant bubbles, launcher shell, and soft fills             |
| `avatarSrc`                              | string                                 | `''`                                                    | Optional URL to a custom avatar image                                                                                    |
| `baseUrl`                                | string                                 | `'http://localhost:8000'`                               | Override the API base URL                                                                                                |
| `placeholder`                            | string                                 | `''`                                                    | Launcher pill text beside the copilot button                                                                             |
| `statusText` / `status-text`             | string                                 | `'Ask anything about your agents, platforms or tools.'` | Header helper text when idle                                                                                             |
| `inputPlaceholder` / `input-placeholder` | string                                 | `'Ask the copilot...'`                                  | Message textarea placeholder                                                                                             |
| `emptyHeading` / `empty-heading`         | string                                 | `'What are we building today?'`                         | Empty-state headline                                                                                                     |
| `emptySubheading` / `empty-subheading`   | string                                 | `'Ask me anything, or pick a starting point below.'`    | Empty-state supporting text                                                                                              |
| `quickActions` / `quick-actions-json`    | array/JSON string                      | Built-in starter cards                                  | Custom quick action cards with `title`, `subtitle`, `prompt`, optional `iconHtml`, or React `icon`                       |
| `fullscreenUrl` / `fullscreen-url`       | string                                 | `''`                                                    | Route to navigate to when fullscreen is requested                                                                        |
| `sidebarTarget` / `sidebar-target`       | CSS selector                           | `'body'`                                                | Element that receives padding when sidebar opens                                                                         |

### Layout behavior

* The launcher is visible for `popup`, `sidebar`, and routed `fullscreen`; clicking it opens the configured mode or updates the browser route with `history.pushState` and opens the fullscreen overlay for `fullscreenUrl`.
* `popup` renders as a floating corner overlay above the current page, like a normal chatbot widget.
* `sidebar` opens as a fixed side panel and shifts `sidebarTarget` with padding instead of covering the main app. Closing or switching away removes that padding.
* `fullscreen` updates the browser route with `history.pushState` and opens the fullscreen overlay for `fullscreenUrl` when provided; on the dedicated route, omit `fullscreenUrl` to render the full-page copilot screen.

### Fullscreen route component

Use the floating widget with `fullscreenUrl` on normal pages, then register a dedicated route that renders the same Copilot in `fullscreen` mode without `fullscreenUrl`:

```tsx theme={null}
// App shell
<Copilot
  apiKey="YOUR_API_KEY"
  agentId={7}
  mode="popup"
  fullscreenUrl="/copilot"
/>

// /copilot route
<Copilot
  apiKey="YOUR_API_KEY"
  agentId={7}
  mode="fullscreen"
  themePrimary="blue"
  themeSecondary="orange"
          themeMode="light"
/>
```

Fullscreen mode renders a full-page ChatGPT-style screen with an expandable/collapsible conversation sidebar.

### React icon quick actions

React wrappers can pass icon provider components directly:

```tsx theme={null}
import { Bot, Plug } from "lucide-react";

<Copilot
  apiKey="YOUR_API_KEY"
  agentId={7}
  quickActions={[
    { icon: <Bot size={16} />, title: "Build an Agent", subtitle: "Start from scratch", prompt: "Help me build an agent" },
    { icon: <Plug size={16} />, title: "Connect Tools", subtitle: "APIs and integrations", prompt: "Help me connect tools" }
  ]}
/>
```

### Vanilla quick actions

Use `quick-actions-json` when configuring the Web Component from HTML:

```html theme={null}
<chatatp-copilot-button
  apiKey="YOUR_API_KEY"
  agentId="7"
  quick-actions-json='[
    {"title":"Build an Agent","subtitle":"Start from scratch","prompt":"Help me build an agent"},
    {"title":"Connect Tools","subtitle":"APIs and integrations","prompt":"Help me connect tools"}
  ]'
></chatatp-copilot-button>
```