@halo-ads/react-sdk

React components and hooks for Halo Ads — AdBanner, AdCard, AdCarousel, and useAd.

Install

pnpm add @halo-ads/react-sdk
# peer deps
pnpm add react react-dom

Setup

Wrap your app (or ad section) with AdProvider:

import { AdProvider } from '@halo-ads/react-sdk';

export default function RootLayout({ children }) {
  return (
    <AdProvider publisherId="pub_xxx" apiKey="pk_live_...">
      {children}
    </AdProvider>
  );
}

Components

<AdBanner>

Standard display banner — renders 728×90 / 300×250 / 320×50 depending on format.

import { AdBanner } from '@halo-ads/react-sdk';

<AdBanner slot="sl_banner_top" format="banner" />

<AdCard>

Elevated card unit with image, headline, body, and CTA button.

import { AdCard } from '@halo-ads/react-sdk';

<AdCard slot="sl_sidebar_card" format="card" />

<AdCarousel>

Swipeable multi-creative carousel.

import { AdCarousel } from '@halo-ads/react-sdk';

<AdCarousel slot="sl_feed_carousel" format="carousel" />

Hooks

useAd(slot, format?)

Fetch an ad and handle loading/error state yourself:

import { useAd } from '@halo-ads/react-sdk';

function MySponsoredSection() {
  const { ad, loading, error } = useAd('sl_native', 'native');

  if (loading) return <Skeleton />;
  if (!ad)    return null;

  return (
    <div>
      <img src={ad.image} alt={ad.title} />
      <p>{ad.description}</p>
      <a href={ad.url}>{ad.ctaText}</a>
    </div>
  );
}

useAdAnalytics()

Access the analytics tracker directly:

import { useAdAnalytics } from '@halo-ads/react-sdk';

const { track } = useAdAnalytics();
track('conversion', { adId: 'ad_xyz', value: 9.99, currency: 'USD' });

See also

• React demo — full Vite + React example
• Next.js demo — App Router + Next.js 14
• @halo-ads/core — underlying implementation