@bannerflex/react

React components and API helpers for BannerFlex. Use this to add BannerFlex-powered popups and analytics to any React app (Next.js, Vite, CRA, etc.) without Framer.

Install

npm install @bannerflex/react
# or
yarn add @bannerflex/react
pnpm add @bannerflex/react

Quick start: Popup

1. Wrap your app (optional but recommended) so you don’t pass baseUrl everywhere:

import { BannerFlexProvider, BannerFlexPopup } from '@bannerflex/react';

function App() {
  return (
    <BannerFlexProvider baseUrl="https://www.bannerflex.app">
      <YourApp />
      <BannerFlexPopup
        bannerId="your-banner-id-from-dashboard"
        campaignId="bnrflx-your-campaign-uuid"
        delay={2}
        frequencyToShow={24}
        dismissOnBackdropPress
        renderCloseButton={(onClose) => (
          <button type="button" onClick={onClose} aria-label="Close">
            ×
          </button>
        )}
      >
        <div style={{ padding: 24, background: 'white', borderRadius: 8 }}>
          <h2>Welcome</h2>
          <p>This popup is powered by BannerFlex.</p>
        </div>
      </BannerFlexPopup>
    </BannerFlexProvider>
  );
}

2. Without a provider — pass baseUrl on the component:

<BannerFlexPopup
  baseUrl="https://www.bannerflex.app"
  bannerId="your-banner-id"
  campaignId="bnrflx-xxx"
  delay={0}
  displayOnDelay
  frequencyToShow={24}
  dismissOnBackdropPress
  renderCloseButton={(onClose) => <button onClick={onClose}>Close</button>}
>
  <div>Your content</div>
</BannerFlexPopup>

Popup props

| Prop | Type | Default | Description | |------|------|--------|-------------| | bannerId | string | required | Banner ID from the BannerFlex dashboard. | | campaignId | string | '' | Campaign ID (e.g. bnrflx-xxx). Use ?campaign=bnrflx-xxx in the URL to preview. | | baseUrl | string | from provider or https://www.bannerflex.app | API base URL. | | delay | number | 0 | Seconds before auto-showing. | | displayOnDelay | boolean | true | If false, the popup only shows when you call ref.current.open(). | | frequencyToShow | number | 24 | Show again after this many hours (since last view). 0 = every time. | | lastTimeUpdated | string | '' | ISO date; if content was updated after the user’s last visit, show again. | | isScheduled | boolean | false | When true, only show between startDate and endDate. | | startDate / endDate | string | '' | ISO date range when isScheduled is true. | | backgroundColor | string | 'rgba(0,0,0,0.5)' | Backdrop overlay color. | | dismissOnBackdropPress | boolean | false | Allow closing by clicking the backdrop. | | zIndex | number | 10000 | z-index of the overlay. | | renderCloseButton | (onClose) => ReactNode | — | Optional close button. | | onClose | () => void | — | Called when the popup closes. |

Programmatic open/close

Use a ref when displayOnDelay={false} to show the popup from a button or other trigger:

import { useRef } from 'react';
import { BannerFlexPopup, type BannerFlexPopupRef } from '@bannerflex/react';

function MyPage() {
  const popupRef = useRef<BannerFlexPopupRef>(null);

  return (
    <>
      <button type="button" onClick={() => popupRef.current?.open()}>
        Show popup
      </button>
      <BannerFlexPopup
        ref={popupRef}
        bannerId="your-banner-id"
        campaignId="bnrflx-xxx"
        displayOnDelay={false}
        renderCloseButton={(onClose) => <button onClick={onClose}>Close</button>}
      >
        <div>Popup content</div>
      </BannerFlexPopup>
    </>
  );
}

Tracking CTA and custom metrics

Inside the popup content:

• CTA click (reported as click): add data-bannerflex-cta to the element (e.g. a button or link).
• Custom metric (reported as custom with a metric ID): add data-bannerflex-metric="your-metric-id" (the ID from your dashboard).

<BannerFlexPopup bannerId="..." campaignId="...">
  <div>
    <a href="/signup" data-bannerflex-cta>Sign up</a>
    <button type="button" data-bannerflex-metric="metric-uuid-from-dashboard">
      Custom action
    </button>
  </div>
</BannerFlexPopup>

API helpers

You can use the same logic the components use for custom UIs or server-side checks:

import {
  shouldShowBanner,
  sendBannerEvent,
  getCampaignFromUrl,
  getCountryFromUrl,
  isWithinSchedule,
} from '@bannerflex/react';

// Check if the banner should show (e.g. geolocation) — async
const show = await shouldShowBanner(
  'https://www.bannerflex.app',
  'banner-id',
  'bnrflx-campaign-id',
  getCountryFromUrl() ?? undefined
);

// Send an impression or click
sendBannerEvent('https://www.bannerflex.app', 'banner-id', 'impression', {
  campaignId: 'bnrflx-xxx',
});

// URL params (for test links from the dashboard)
const campaign = getCampaignFromUrl(); // ?campaign=bnrflx-xxx
const country = getCountryFromUrl();   // ?country=GB

// Schedule check
const inRange = isWithinSchedule('2025-01-01', '2025-12-31');

Test links

From the BannerFlex dashboard, use the campaign’s Test link. It includes ?campaign=bnrflx-xxx (and optionally &country=XX, &date=YYYY-MM-DD). When that query is present, the popup uses it to force that campaign and (if provided) geo/date for preview.

License

MIT