Skip to main content

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.

​
FanfareProvider

The FanfareProvider component initializes the Fanfare SDK and makes it available to all child components via React Context.

​
Basic Usage

import { FanfareProvider } from "@waitify-io/fanfare-sdk-react";

function App() {
  return (
    <FanfareProvider organizationId="org_xxx" publishableKey="pk_live_xxx">
      <YourApp />
    </FanfareProvider>
  );
}

​
Props

​
FanfareProviderProps

interface FanfareProviderProps extends FanfareConfig {
  children: React.ReactNode;

  /**
   * Whether to automatically restore session on mount
   * @default true
   */
  autoRestore?: boolean;

  /**
   * Whether to automatically resume operations after restore
   * @default true
   */
  autoResume?: boolean;

  /**
   * Loading component to show while initializing
   */
  loadingComponent?: React.ReactNode;

  /**
   * Locale for translations
   * @default "en"
   */
  locale?: Locale;

  /**
   * Custom translations to merge with or override defaults
   */
  translations?: PartialTranslationMessages;
}

​
Required Props

PropTypeDescription
organizationIdstringYour Fanfare organization ID
publishableKeystringYour publishable API key
childrenReactNodeChild components

​
Optional Props

PropTypeDefaultDescription
autoRestorebooleantrueRestore session on mount
autoResumebooleantrueResume operations after restore
loadingComponentReactNodenullLoading UI during initialization
localeLocale"en"Translation locale
translationsPartialTranslationMessagesundefinedCustom translations
environmentstring"production"API environment
debugbooleanfalseEnable debug logging

​
Configuration Examples

​
With Loading State

function App() {
  return (
    <FanfareProvider organizationId="org_xxx" publishableKey="pk_live_xxx" loadingComponent={<LoadingSpinner />}>
      <YourApp />
    </FanfareProvider>
  );
}

function LoadingSpinner() {
  return (
    <div className="loading-container">
      <div className="spinner" />
      <p>Loading...</p>
    </div>
  );
}

​
With Custom Translations

function App() {
  return (
    <FanfareProvider
      organizationId="org_xxx"
      publishableKey="pk_live_xxx"
      translations={{
        "queue.enter": "Join the Line",
        "queue.leave": "Leave the Line",
        "admitted.cta": "Go to Checkout",
        "draw.enter": "Enter the Raffle",
      }}
    >
      <YourApp />
    </FanfareProvider>
  );
}

​
With Locale

function App() {
  const [locale, setLocale] = useState<Locale>("en");

  return (
    <FanfareProvider organizationId="org_xxx" publishableKey="pk_live_xxx" locale={locale}>
      <LocaleSwitcher onChange={setLocale} />
      <YourApp />
    </FanfareProvider>
  );
}

​
Development Configuration

function App() {
  return (
    <FanfareProvider organizationId="org_xxx" publishableKey="pk_test_xxx" environment="development" debug={true}>
      <YourApp />
    </FanfareProvider>
  );
}

​
Disable Auto-Restore

function App() {
  return (
    <FanfareProvider organizationId="org_xxx" publishableKey="pk_live_xxx" autoRestore={false} autoResume={false}>
      <YourApp />
    </FanfareProvider>
  );
}

​
Initialization Lifecycle

The provider follows this lifecycle:
  1. Mount - Provider renders loadingComponent
  2. Initialize - SDK is initialized with config
  3. Restore (if autoRestore) - Session is restored from storage
  4. Resume (if autoResume) - Active operations are resumed
  5. Ready - Children are rendered with SDK context
// Visual representation of the lifecycle
function ProviderLifecycle() {
  /*
   * Phase 1: Initializing
   * - loadingComponent is shown
   * - SDK is being initialized
   *
   * Phase 2: Restoring (if autoRestore)
   * - loadingComponent is still shown
   * - Session is being restored
   *
   * Phase 3: Resuming (if autoResume)
   * - loadingComponent is still shown
   * - Polling is being restarted
   *
   * Phase 4: Ready
   * - Children are rendered
   * - SDK is available via useFanfare()
   */
}

​
Error Handling

If initialization fails, the provider logs an error and renders null: 
function App() {
  return (
    <ErrorBoundary fallback={<InitializationError />}>
      <FanfareProvider organizationId="org_xxx" publishableKey="pk_live_xxx">
        <YourApp />
      </FanfareProvider>
    </ErrorBoundary>
  );
}

class ErrorBoundary extends React.Component {
  state = { hasError: false };

  static getDerivedStateFromError() {
    return { hasError: true };
  }

  render() {
    if (this.state.hasError) {
      return this.props.fallback;
    }
    return this.props.children;
  }
}

​
Environment Variables

Configure the provider with environment variables: 
// Next.js
function App() {
  return (
    <FanfareProvider
      organizationId={process.env.NEXT_PUBLIC_FANFARE_ORG_ID!}
      publishableKey={process.env.NEXT_PUBLIC_FANFARE_KEY!}
    >
      <YourApp />
    </FanfareProvider>
  );
}

// Vite
function App() {
  return (
    <FanfareProvider
      organizationId={import.meta.env.VITE_FANFARE_ORG_ID}
      publishableKey={import.meta.env.VITE_FANFARE_KEY}
    >
      <YourApp />
    </FanfareProvider>
  );
}

​
Multiple Providers

For multi-organization scenarios, use separate providers: 
function MultiOrgApp() {
  return (
    <>
      <FanfareProvider organizationId="org_aaa" publishableKey="pk_live_aaa">
        <OrgAApp />
      </FanfareProvider>

      <FanfareProvider organizationId="org_bbb" publishableKey="pk_live_bbb">
        <OrgBApp />
      </FanfareProvider>
    </>
  );
}

​
Cleanup

The provider automatically cleans up the SDK when unmounted: 
function ConditionalFanfare() {
  const [enabled, setEnabled] = useState(true);

  return (
    <>
      <button onClick={() => setEnabled(!enabled)}>Toggle</button>

      {enabled && (
        <FanfareProvider organizationId="org_xxx" publishableKey="pk_live_xxx">
          <YourApp />
        </FanfareProvider>
      )}
    </>
  );
}
When the provider unmounts:
  • SDK destroy() is called
  • All polling is stopped
  • Event subscriptions are cleaned up
  • Pending beacon events are flushed

​
TypeScript

import type { FanfareProviderProps } from "@waitify-io/fanfare-sdk-react";
import type { Locale, PartialTranslationMessages } from "@waitify-io/fanfare-sdk-react";

const config: Omit<FanfareProviderProps, "children"> = {
  organizationId: "org_xxx",
  publishableKey: "pk_live_xxx",
  locale: "en",
  translations: {
    "queue.enter": "Join the Waitlist",
  },
};

function App() {
  return (
    <FanfareProvider {...config}>
      <YourApp />
    </FanfareProvider>
  );
}

​
Next Steps