> ## 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`). If omitted, the PAL's `greeting` or `dynamic_greeting` applies. |
| `memory-stores` | string | Comma-separated memory tags (maps to `memory_stores`). Optional — automatic per-visitor memory is on by default. Pass a stable per-user identifier when you want memory to follow a specific user instead. |

## 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. If you omit it, the PAL's `greeting` or `dynamic_greeting` applies. 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 tag is a memory namespace: every conversation that uses the same tag shares one bucket of memories, so the PAL can remember that user across sessions and devices.

Tags 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:

```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>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.