> For the complete documentation index, see [llms.txt](https://docs.toucanai.cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.toucanai.cloud/embed/embedding-methods/web-component-embedding.md).

# Web Component embedding

{% hint style="info" %}
**Target Audience**: Developers
{% endhint %}

### TL;DR

Toucan AI utilizes a standards-based web component to enable framework-agnostic embedding of analytics through a custom HTML element.

***

### When to use this

Choose this method to maintain a portable analytics layer that works across any web stack—including React, Vue, Angular, or plain HTML—without requiring a dedicated SDK or complex build dependencies.

***

### Functional Overview

The web component is a self-contained unit of code that wraps Toucan AI visualizations into a custom HTML tag. This approach leverages native browser technologies to ensure that dashboards and charts render consistently regardless of the host application's underlying framework.

```html
<script type="module" src="https://toucanai.cloud/embed/embed.js"></script>
<tc-dashboard
    dashboard-id="your-dashboard-id"
    auth-token="your-embed-token"
    server-url="https://toucanai.cloud/api"
    data-theme="light"
    style="width: 100%; height: 600px;"
></tc-dashboard>
```

A published custom front embeds the same way, under its own tag. It fills the box it is given, so set a height, and every query it runs is scoped by the token holder's data access rules:

```html
<script type="module" src="https://toucanai.cloud/embed/embed.js"></script>
<tc-custom-front
    custom-front-id="your-custom-front-id"
    auth-token="your-embed-token"
    server-url="https://toucanai.cloud/api"
    data-theme="light"
    style="display: block; width: 100%; height: 100vh;"
></tc-custom-front>
```

***

### Core Attributes

The behavior and content of the web component are controlled through declarative HTML attributes:

| Attribute                                     | Required | Description                                                    |
| --------------------------------------------- | -------- | -------------------------------------------------------------- |
| **dashboard-id / chart-id / custom-front-id** | ✅        | The unique identifier for the Toucan AI resource to render.    |
| **auth-token**                                | ✅        | A secure, server-generated JWT used for session authorization. |
| **server-url**                                | ✅        | The API endpoint for your specific Toucan AI instance.         |
| **data-theme**                                | ❌        | Optional setting to toggle between "light" or "dark" modes.    |

***

### Architectural Advantages

* **Framework Independence**: The component runs natively in the browser, eliminating the risk of framework lock-in or version conflicts.
* **Zero Build Overhead**: Integration requires no npm installations or specialized build-time configurations.
* **Encapsulated Logic**: All rendering logic, data fetching, and interactivity are handled internally by the component.
* **Token-Driven Security**: Access control is strictly managed through server-side generated tokens, protecting sensitive API keys.

***

### Limitations

* **Interactivity Constraints**: Advanced programmatic interactivity may require the SDK or API-driven methods.
* **Session Isolation**: Authentication is limited to the embed token; the component does not share user sessions with the host application.