Web Component embedding

TL;DRCopy Anchor Link

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

When to use thisCopy Anchor Link

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 OverviewCopy Anchor Link

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>

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:

<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 AttributesCopy Anchor Link

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

Architectural AdvantagesCopy Anchor Link

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

LimitationsCopy Anchor Link

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