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

# Widget

> Add a floating Tavus conversation launcher to any website with the <tavus-widget> custom element.

## Overview

`<tavus-widget>` renders a floating launcher that expands into a full Tavus conversation popup. It is the fastest way to put a deployment on a page: one script tag, one element, no backend.

The widget validates the deployment, creates the conversation, and manages the entire call lifecycle. It renders in a shadow DOM, so it is isolated from your page styles.

## Installation

<Tabs>
  <Tab title="CDN (static pages)">
    Add the element and the script tag anywhere in your HTML:

    ```html theme={null}
    <tavus-widget deployment-id="YOUR_DEPLOYMENT_ID"></tavus-widget>
    <script src="https://unpkg.com/@tavus/widget"></script>
    ```

    To pin an exact version instead of tracking the latest beta, use a versioned URL such as `https://unpkg.com/@tavus/widget@0.1.0`.
  </Tab>

  <Tab title="npm (bundler / framework apps)">
    ```bash theme={null}
    npm install @tavus/widget@latest
    ```

    Importing the package registers the `<tavus-widget>` custom element as a side effect:

    ```ts theme={null}
    import "@tavus/widget";
    ```

    After that you can use the tag anywhere in your app's markup - including JSX:

    ```tsx theme={null}
    <tavus-widget deployment-id="YOUR_DEPLOYMENT_ID" />
    ```
  </Tab>
</Tabs>

## Attributes

| Attribute                | Type   | Description                                                                                                                                                                                    |
| ------------------------ | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `deployment-id`          | string | The Tavus deployment ID. Fetches configuration from `/v2/deployments/:id/init`.                                                                                                                |
| `conversational-context` | string | Extra context injected into the conversation at start (maps to `conversational_context`). Use it to pass what the deployment should know about the current user or page.                       |
| `custom-greeting`        | string | Overrides the PAL's opening line for this conversation (maps to `custom_greeting`).                                                                                                            |
| `memory-stores`          | string | Comma-separated list of memory store IDs (maps to `memory_stores`). Pass a stable per-user identifier to give that user consistent, persistent memory across every conversation with this PAL. |

## Context and greeting

`conversational-context` and `custom-greeting` let you tailor a single conversation at start time:

```html theme={null}
<tavus-widget
  deployment-id="YOUR_DEPLOYMENT_ID"
  conversational-context="The user is Jane, on the Pro plan, viewing the billing page."
  custom-greeting="Hey Jane, welcome back - want to pick up where we left off?"
></tavus-widget>
<script src="https://unpkg.com/@tavus/widget"></script>
```

`conversational-context` overrides the deployment's configured default context for this conversation; when omitted, the deployment default is used. `custom-greeting` sets the PAL's opening line. Empty or whitespace-only values are ignored, so an empty attribute behaves the same as not setting it.

## Persistent memory

`memory-stores` lets a returning user pick up where they left off. A store ID is a memory namespace: every conversation that uses the same store ID shares one bucket of memories, so the PAL can remember that user across sessions and devices. See [Memories](/sections/conversational-video-interface/memories) for how memory stores work on the API.

Store IDs are global to your account, **not** scoped to a deployment. A bare `user-12345` would share the same memory across every deployment that uses it. To keep memory specific to one deployment, combine the deployment ID with your user ID (similar to namespacing with PAL ID in the [Memories guide](/sections/conversational-video-interface/memories#basic-example)):

```html theme={null}
<tavus-widget
  deployment-id="YOUR_DEPLOYMENT_ID"
  memory-stores="YOUR_DEPLOYMENT_ID-user-12345"
></tavus-widget>
<script src="https://unpkg.com/@tavus/widget"></script>
```

Pass multiple stores as a comma-separated list (`memory-stores="YOUR_DEPLOYMENT_ID-user-12345,team-acme"`). Empty or whitespace-only values are ignored.

<Note>
  In the [PAL Maker](https://maker.tavus.io/dev), open your deployment's **Settings** and use **Unique memory per visitor** (maps to `customization.conversation.unique_memory_tag`; on by default). When that toggle is on and you omit `memory-stores`, the widget or embed generates an anonymous per-browser ID (stored in `localStorage`, scoped to that deployment) and sends it as `memory_stores` on each conversation start. Memory persists for that visitor in the same browser, but not across devices or after storage is cleared. Set `memory-stores` to your own stable user ID when you want memory to follow a logged-in user everywhere. With the toggle off and no `memory-stores` attribute, no memory store is sent.
</Note>

## Appearance

The launcher's look and placement are part of the deployment's configuration in the [PAL Maker](https://maker.tavus.io/dev) - no markup changes required:

| Setting    | Values                                                                  | Description                                                    |
| ---------- | ----------------------------------------------------------------------- | -------------------------------------------------------------- |
| Variant    | `tiny`, `compact`, `full`                                               | Size and detail level of the collapsed launcher.               |
| Position   | `bottom-right`, `bottom-left`, `top-right`, `top-left`, `top`, `bottom` | Where the launcher floats on the page.                         |
| Expandable | `default`, `always`, `start-expanded`                                   | How and when the launcher expands into the conversation popup. |
| Avatar     | `orb`, `image`                                                          | The launcher's avatar treatment.                               |

## Interacting from the page

The widget emits lifecycle events (`tavus:conversation-started`, `tavus:tool-call`, …) and exposes an imperative API for starting, ending, and messaging the conversation. See [Host communication](/sections/deployments/host-communication) for the full reference.

<Note>
  The widget positions itself relative to the viewport, so it can be placed anywhere in the document - typically just before the closing `</body>` tag.
</Note>