Skip to main content

​
Widgets Overview

The Fanfare SDK provides pre-built widget components through the @waitify-io/fanfare-sdk-solid package. These widgets can be used in React applications via web components.

​
Architecture

Widgets are built with SolidJS for optimal performance and bundle size, then exposed as web components that work with any framework, including React. 
┌─────────────────────────────────────────────────────────────┐
│                    Your React App                           │
├─────────────────────────────────────────────────────────────┤
│  React Hooks (for custom UIs)                               │
│  - useQueue, useDraw, useAuction, etc.                      │
├─────────────────────────────────────────────────────────────┤
│  Web Components (for drop-in widgets)                       │
│  - <fanfare-queue-widget>                                   │
│  - <fanfare-draw-widget>                                    │
│  - <fanfare-auction-widget>                                 │
│  - <fanfare-experience-widget>                              │
├─────────────────────────────────────────────────────────────┤
│  @waitify-io/fanfare-sdk-solid                              │
│  (Compiled to Web Components)                               │
└─────────────────────────────────────────────────────────────┘

​
Available Widgets

WidgetWeb ComponentDescription
ExperienceWidget<fanfare-experience-widget>Complete journey orchestration
QueueWidget<fanfare-queue-widget>Virtual waiting room
DrawWidget<fanfare-draw-widget>Lottery/raffle entry
AuctionWidget<fanfare-auction-widget>Real-time bidding
WaitlistWidget<fanfare-waitlist-widget>Pre-launch signup
TimedReleaseWidget<fanfare-timed-release-widget>Flash sale window

​
Using Web Components in React

​
Installation

npm install @waitify-io/fanfare-sdk-solid

​
Registration

Register the web components once in your app: 
// app.tsx or index.tsx
import { registerWebComponents } from "@waitify-io/fanfare-sdk-solid";

// Register all widgets with default config
registerWebComponents({
  organizationId: "org_xxx",
  publishableKey: "pk_live_xxx",
});

​
Usage

// In any React component
function QueuePage() {
  return (
    <div className="queue-container">
      <h1>Join Our Queue</h1>
      <fanfare-queue-widget queue-id="queue_123" show-header="true" show-actions="true" />
    </div>
  );
}

​
TypeScript Support

Add type declarations for web components: 
// global.d.ts
declare namespace JSX {
  interface IntrinsicElements {
    "fanfare-queue-widget": React.DetailedHTMLProps<
      React.HTMLAttributes<HTMLElement> & {
        "queue-id": string;
        "show-header"?: string;
        "show-actions"?: string;
        "show-estimated-wait"?: string;
      },
      HTMLElement
    >;
    "fanfare-draw-widget": React.DetailedHTMLProps<
      React.HTMLAttributes<HTMLElement> & {
        "draw-id": string;
        "show-header"?: string;
        "show-countdown"?: string;
        "show-actions"?: string;
      },
      HTMLElement
    >;
    "fanfare-auction-widget": React.DetailedHTMLProps<
      React.HTMLAttributes<HTMLElement> & {
        "auction-id": string;
        "show-header"?: string;
        "show-bid-history"?: string;
        "show-countdown"?: string;
        "currency-code"?: string;
      },
      HTMLElement
    >;
    "fanfare-waitlist-widget": React.DetailedHTMLProps<
      React.HTMLAttributes<HTMLElement> & {
        "waitlist-id": string;
        "show-header"?: string;
        "show-countdown"?: string;
        "show-actions"?: string;
      },
      HTMLElement
    >;
    "fanfare-timed-release-widget": React.DetailedHTMLProps<
      React.HTMLAttributes<HTMLElement> & {
        "timed-release-id": string;
        "checkout-url"?: string;
        "show-header"?: string;
        "show-countdown"?: string;
        "show-actions"?: string;
      },
      HTMLElement
    >;
    "fanfare-experience-widget": React.DetailedHTMLProps<
      React.HTMLAttributes<HTMLElement> & {
        "experience-id": string;
        "auto-start"?: string;
        "access-code"?: string;
        "auto-enter-waitlist"?: string;
        "checkout-url"?: string;
      },
      HTMLElement
    >;
  }
}

​
Event Handling

Web components emit custom events that you can listen to: 
import { useEffect, useRef } from "react";

function QueueWithEvents() {
  const widgetRef = useRef<HTMLElement>(null);

  useEffect(() => {
    const widget = widgetRef.current;
    if (!widget) return;

    const handleEnter = (e: CustomEvent) => {
      console.log("Entered queue:", e.detail.queueId);
    };

    const handleAdmitted = (e: CustomEvent) => {
      console.log("Admitted with token:", e.detail.token);
      window.location.href = `/checkout?token=${e.detail.token}`;
    };

    widget.addEventListener("fanfare-queue-enter", handleEnter);
    widget.addEventListener("fanfare-queue-admitted", handleAdmitted);

    return () => {
      widget.removeEventListener("fanfare-queue-enter", handleEnter);
      widget.removeEventListener("fanfare-queue-admitted", handleAdmitted);
    };
  }, []);

  return <fanfare-queue-widget ref={widgetRef} queue-id="queue_123" />;
}

​
Available Events

Queue Widget:
  • fanfare-queue-enter - User entered queue
  • fanfare-queue-leave - User left queue
  • fanfare-queue-position-change - Position updated
  • fanfare-queue-admitted - User admitted
Draw Widget:
  • fanfare-draw-enter - User entered draw
  • fanfare-draw-withdraw - User withdrew
  • fanfare-draw-result - Draw result received
  • fanfare-draw-proceed - User proceeding to checkout
Auction Widget:
  • fanfare-auction-bid - Bid placed
  • fanfare-auction-outbid - User was outbid
  • fanfare-auction-win - User won auction
  • fanfare-auction-proceed - User proceeding to checkout
Experience Widget:
  • fanfare-journey-change - Journey state changed
  • fanfare-admitted - User admitted
  • fanfare-error - Error occurred

​
Styling

​
CSS Variables

Widgets use CSS custom properties for theming: 
/* In your global CSS */
:root {
  --fanfare-primary: #3b82f6;
  --fanfare-primary-hover: #2563eb;
  --fanfare-background: #ffffff;
  --fanfare-foreground: #1f2937;
  --fanfare-muted: #f3f4f6;
  --fanfare-border: #e5e7eb;
  --fanfare-radius: 0.5rem;
}

​
Theme Configuration

Pass theme config during registration: 
registerWebComponents({
  organizationId: "org_xxx",
  publishableKey: "pk_live_xxx",
  themeConfig: {
    colors: {
      primary: "#8b5cf6",
      background: "#0f172a",
      foreground: "#f8fafc",
    },
    borderRadius: "lg",
  },
  variant: "rounded", // "default" | "rounded" | "retro" | "clean"
});

​
Container Styling

<fanfare-queue-widget
  queue-id="queue_123"
  container-class="my-custom-widget"
/>

<style>
.my-custom-widget {
  max-width: 400px;
  margin: 0 auto;
  padding: 1rem;
}
</style>

​
Custom UIs with Hooks

For maximum customization, use React hooks instead of widgets: 
import { useQueue } from "@waitify-io/fanfare-sdk-react";

function CustomQueueUI() {
  const { queue, status, position, enter, leave } = useQueue("queue_123");

  // Build your own UI with full control
  return <div className="my-queue-ui">{/* Your custom design */}</div>;
}
See the Hooks documentation for details.

​
Comparison

ApproachBest ForCustomizationBundle Size
Web ComponentsQuick integrationTheme + CSS onlySmallest
React HooksCustom UIsFull controlMedium

​
Next Steps