react

@gravity-ai/react

React components for rendering Gravity ads with automatic impression and click tracking.

Installation

npm install @gravity-ai/react

Peer dependency: React 17+

Quick Start

import { GravityAd } from '@gravity-ai/react';

function ChatResponse({ ads }) {
  return ads.map((ad, i) => <GravityAd key={i} ad={ad} />);
}

That's it. The component renders a styled ad card using inline styles and automatically fires the impression pixel when the ad scrolls into view.

API Response Shape

The components expect the objects returned by the Gravity API:

interface AdResponse {
  adText: string;
  title?: string;
  cta?: string;
  brandName?: string;
  url?: string;
  favicon?: string;
  impUrl?: string;   // impression tracking pixel
  clickUrl?: string;  // click-through URL
}

Components

<GravityAd />

Full-featured ad card with favicon, brand name, title, body text, and CTA button. All styles are inline — no injected stylesheets, no CSS class names, no CSS-in-JS. What you see in the JSX is what renders.

<GravityAd
  ad={ad}
  variant="card"       // "card" | "inline" | "minimal"
  showLabel={true}     // show "Sponsored" label
  labelText="Sponsored"
  openInNewTab={true}
  onImpression={() => console.log('seen')}
  onClickTracked={() => console.log('clicked')}
/>

Variants:

Variant	Description
card	Default. Vertical card with border, shadow, and padding.
inline	Horizontal layout for sidebars or toolbars.
minimal	No border, shadow, or background. Blends with host content.

Styling with style and slotProps

Override the outer container with the style prop:

<GravityAd ad={ad} style={{ maxWidth: 400, borderRadius: 16 }} />

Override any inner element with slotProps:

<GravityAd
  ad={ad}
  slotProps={{
    cta: { style: { background: '#E11D48', borderRadius: 999 } },
    label: { style: { display: 'none' } },
    title: { style: { fontSize: 16 } },
  }}
/>

Each slotProps key maps to a DOM element:

Key	Element	What it controls
container	Outer <a>	Same as top-level style prop
inner	Padding wrapper <div>	Layout, padding, gap
header	Header row <div>	Favicon + brand + label row
favicon	Favicon <img>	Size, border-radius
brand	Brand name <span>	Font, color
label	"Sponsored" <span>	Pill styling, visibility
body	Body wrapper <div>	Title + text layout
title	Title <p>	Font, color
text	Ad text <p>	Font, color
cta	CTA button <span>	Background, border-radius, padding

Each slot accepts { style?: CSSProperties; className?: string }.

For the full styling guide with DOM structure and common recipes, see STYLING.md.

<AdText />

Unstyled text-only renderer. Use when you want full control over presentation.

<AdText
  ad={ad}
  className="my-custom-style"
  style={{ fontSize: 14 }}
/>

Renders ad.adText as a link (if clickUrl exists) or a span. No built-in styles beyond text-decoration: none; color: inherit.

Impression Tracking

Both components use IntersectionObserver to fire the impression pixel only when the ad is actually visible to the user (50% of the element in the viewport). This is a significant improvement over fire-on-mount — publishers won't report impressions for ads rendered below the fold that were never seen.

The impression fires exactly once per ad. If the ad object changes (different impUrl), the tracking resets for the new ad.

To disable automatic tracking:

<GravityAd ad={ad} disableImpressionTracking />

Hooks

useAdTracking

Low-level hook for building fully custom ad components:

import { useAdTracking } from '@gravity-ai/react';

function CustomAd({ ad }) {
  const { containerRef, handleClick } = useAdTracking({
    ad,
    onImpression: () => console.log('impression fired'),
    onClickTracked: () => console.log('click tracked'),
  });

  return (
    <a ref={containerRef} href={ad.clickUrl} onClick={handleClick}>
      {ad.adText}
    </a>
  );
}

The hook returns:

• containerRef — attach to the DOM element for IntersectionObserver-based impression tracking
• handleClick — call on click to fire the click tracking callback
• impressionFired — boolean indicating whether the impression has already been fired

License

MIT