Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.trygravity.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
The pre-built React component

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

<GravityAd ad={ads[0]} variant="card" />
That’s the minimum. GravityAd takes the ad object from your server, renders it, fires the impression pixel on visibility (IntersectionObserver), and routes clicks through the tracked URL. You do not need to manage any of that yourself.

​
Variants — pick what fits your UI

The component ships 20+ visual treatments out of the box:
VariantShape
cardBordered card with favicon, title, body, CTA. Most common.
inlineCompact inline chip.
minimalSingle-line text with subtle CTA.
bubbleChat-bubble-styled.
pillHorizontal pill.
bannerHorizontal banner, full-width.
hyperlinkUnderlined link only.
text-linkText with inline link.
spotlight, accent, side-panel, labeled, embed, split-action, divider, toolbar, tooltip, notification, contextual, native, footnote, quote, suggestionAdditional styles — see playground.
Try variants live at react-sandbox.trygravity.ai.

​
Style overrides

Pass slotProps to override individual elements: 
<GravityAd
  ad={ads[0]}
  variant="card"
  slotProps={{
    container: { style: { borderRadius: 16, maxWidth: 640 } },
    title: { className: 'my-title-class' },
    cta: { style: { backgroundColor: '#6366F1' } },
  }}
/>
Available slots: container, inner, header, favicon, brand, label, body, title, text, cta, plus variant-specific slots (iconWrapper, accentBar, secondaryCta, footer, arrow, contextHeader).

​
Props reference

PropTypeDescription
adAdResponse | nullThe ad from gravity.getAds().
variantvariant nameVisual treatment.
className, styleCSS propsApplied to the outer wrapper.
slotPropsobjectTargeted style/className overrides (see above).
showLabelbooleanShow/hide the “Sponsored” label. Default true.
labelTextstringOverride the label text. Default "Sponsored".
onClick() => voidFires on click.
onImpression() => voidFires when impression pixel fires.
onClickTracked() => voidFires after the click tracking URL hits.
fallbackReactNodeWhat to render when ad is null. Default nothing.
disableImpressionTrackingbooleanSkip auto impression pixel — you fire it yourself.
openInNewTabbooleanOpen landing page in new tab. Default true.

​
Custom rendering

You don’t have to use GravityAd. The ad object is all you need: 
function MyAd({ ad }) {
  // Fire impression when visible
  const ref = useRef(null);
  useEffect(() => {
    if (!ref.current || !ad) return;
    const observer = new IntersectionObserver(([entry]) => {
      if (entry.isIntersecting) {
        new Image().src = ad.impUrl;  // fire impression pixel
        observer.disconnect();
      }
    });
    observer.observe(ref.current);
    return () => observer.disconnect();
  }, [ad]);

  if (!ad) return null;

  return (
    <a ref={ref} href={ad.clickUrl} target="_blank" rel="noopener">
      <img src={ad.favicon} alt="" />
      <span>{ad.brandName}</span>
      <p>{ad.adText}</p>
      <button>{ad.cta}</button>
    </a>
  );
}
Two must-dos for custom renderers:
  1. Use ad.clickUrl as the href — never ad.url directly. clickUrl routes through Gravity’s tracking and 302s to the landing page, ensuring the click is counted for billing and reporting.
  2. Fire ad.impUrl exactly once, when the ad first becomes visible. A single pixel request: new Image().src = ad.impUrl.

​
Multiple placements

<div className="response">
  <p>{response}</p>
  {ads[0] && <GravityAd ad={ads[0]} variant="card" />}
</div>

<aside className="sidebar">
  {ads[1] && <GravityAd ad={ads[1]} variant="side-panel" />}
</aside>
The ads array is ordered to match the placements array you sent on the request.

​
Variants for the engine to choose

When experiments are active, the engine assigns a variant per session. Let the engine’s choice win by default: 
<GravityAd ad={ad} variant={ad.variant ?? 'card'} />
If the engine has no opinion (no experiment running), ad.variant is undefined and your 'card' default applies.

​
Next

Experiments

How the engine optimizes your creative mix.

Pixel

Drop gr-pix.js on your site — SDK auto-picks up the visitor ID for better attribution.