Web Components

Use web components when you need to embed Fanfare into static HTML, a CMS, or a host framework where mounting React is not practical.

Install

pnpm add @fanfare-io/fanfare-sdk-core @fanfare-io/fanfare-sdk-solid solid-js

Register the element

<script type="module">
  import { registerWebComponents } from "@fanfare-io/fanfare-sdk-solid";

  registerWebComponents({
    organizationId: "org_123",
    publishableKey: "pk_live_123",
  });
</script>

Call registerWebComponents() once before rendering Fanfare custom elements.

<fanfare-experience-widget
  experience-id="exp_123"
  auto-start
  checkout-url="/checkout"
></fanfare-experience-widget>

<fanfare-experience-widget> is the supported custom element for the full journey. It renders the same public journey states as the React ExperienceWidget.

Attributes

Attribute	Purpose
`experience-id`	Required experience ID.
`organization-id`	Optional per-element organization override.
`publishable-key`	Optional per-element publishable key override.
`environment`	SDK environment (production or development).
`api-url`	Custom API URL that overrides environment.
`debug`	Enables SDK debug logging.
`auto-restore`	Restore a persisted session on load (default true).
`auto-resume`	Resume active journeys after restore (default true).
`auto-start`	Starts the journey when the element is ready.
`auto-enter-waitlist`	Automatically joins the waitlist when the routed sequence is in its scheduled phase and offers a waitlist attachment.
`access-code`	Provides an access code when starting or rerouting.
`checkout-url`	Destination for the default granted CTA.
`locale`	Locale for built-in text.
`translations`	JSON object of translation overrides.
`theme-config`	JSON object matching `BrandTheme`.
`variant`	`default`, `retro`, `rounded`, or `clean`.
`container-class`	CSS class applied to the widget container.

Theme and copy

<fanfare-experience-widget
  experience-id="exp_123"
  auto-start
  locale="en"
  variant="rounded"
  theme-config='{"primary":"#0F766E","fontFamily":"Inter, system-ui, sans-serif"}'
  translations='{"queue.enter":"Join the line","granted.cta":"Shop now"}'
></fanfare-experience-widget>

Use valid JSON for theme-config and translations.

Events

Web component events bubble and are composed, so they can be handled by the host page.

<script>
  const widget = document.querySelector("fanfare-experience-widget");

  widget.addEventListener("fanfare-journey-change", (event) => {
    console.log("Journey changed", event.detail.experienceId);
  });

  widget.addEventListener("fanfare-granted", (event) => {
    const grant = event.detail.grant;
    fetch("/api/fanfare/admission", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ grant }),
    }).then(() => {
      window.location.assign("/checkout");
    });
  });

  widget.addEventListener("fanfare-error", (event) => {
    console.error("Fanfare error", event.detail.error);
  });
</script>

Avoid sending grant or raw snapshot details to third-party logs or analytics.

Start Here

Core SDK

Components

Shopify

Examples

Reference

Install

Register the element

Render the widget

Attributes

Theme and copy

Events

​Install

​Register the element

​Render the widget

​Attributes

​Theme and copy

​Events

Install

Register the element

Render the widget

Attributes

Theme and copy

Events