Getting Started

1. Install the packages

npm install fansunited-frontend-components fansunited-frontend-core fansunited-sdk-esm

yarn add fansunited-frontend-components fansunited-frontend-core fansunited-sdk-esm

Note: fansunited-frontend-core provides shared types and utilities; fansunited-frontend-components provides the UI; fansunited-sdk-esm is the Fans United JavaScript SDK that powers data fetching and user actions.

Peer dependencies

{
  "react": ">=16.8.0",
  "react-dom": ">=16.8.0"
}

2. Create an SDK instance

Every component takes an sdk prop. Create one SDK instance and reuse it across components and pages.

import { FansUnitedSDK } from "fansunited-sdk-esm";

export const sdk = FansUnitedSDK({
  // your project configuration
});

For the full SDK configuration reference, see the SDK documentation.

3. Render your first component

import React from "react";
import { ClassicQuizPlay } from "fansunited-frontend-components";
import { WidgetTemplate } from "fansunited-frontend-core";
import { sdk } from "./sdk";

export const App: React.FC = () => (
  <ClassicQuizPlay
    entityId="your-quiz-id"
    sdk={sdk}
    template={WidgetTemplate.STANDARD}
    language="en"
  />
);

That's it. The component renders inside its own shadow DOM, fetches the quiz from the SDK, and handles the entire flow — sign-in (if required), play, scoring, and results.

4. Customize

All components share the same configuration surface for theming, lead collection, CTAs, and rules. See Core Concepts — those pages cover configuration that applies across most components, so each component page can stay focused on its component-specific behavior.

Bundle and styling notes

• Shadow DOM: every component renders inside its own shadow root. Host CSS will not affect the widget, and widget CSS will not leak out.
• Emotion: styling uses Emotion under the hood inside each shadow root.
• Tree-shaking: only the components you import are bundled.
• SSR: components must render on the client (they rely on shadow DOM). In Next.js, dynamic import with ssr: false or render inside a useEffect-gated wrapper.

Common questions

Do I need a separate React copy for the widgets? No. Components peer-depend on the React already in your app. There is no duplicate React runtime.

Can I use multiple components on the same page? Yes. Each component is independent and isolated via its own shadow root.

Does each component need its own SDK instance? No. Create one SDK instance per app and pass it to every component.

How do I theme the widgets? Pass themeOptions per component, or once via ThemeProvider. See Theming.