> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fanfare.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Web Components

> Embed Fanfare with a framework-agnostic custom element.

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

```bash theme={null}
pnpm add @fanfare-io/fanfare-sdk-core @fanfare-io/fanfare-sdk-solid solid-js
```

## Register the element

```html theme={null}
<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.

## Render the widget

```html theme={null}
<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

```html theme={null}
<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.

```html theme={null}
<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.