Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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>

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:

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.

PreviousEmbedding methods
NextWhite-Labelling & Branding

Last updated

Was this helpful?