Web Component embedding

Target Audience: Developers

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.

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