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

***

### Core Attributes

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

| Attribute                   | Required | Description                                                    |
| --------------------------- | -------- | -------------------------------------------------------------- |
| **dashboard-id / chart-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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.toucanai.cloud/embed/embedding-methods/web-component-embedding.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.