React Components - NotPixel Docs

Pre-built React components for rendering ads with automatic impression tracking.

Installation

Install the SDK:


npm install notpixel

Import notpixel/react.css once in your app layout to use the default AdCard style. For a fully custom layout, render the structured ad with your own components and use browser tracking.

React 18+ is required as a peer dependency.

Quick Start


import { AdCard, AdBanner } from 'notpixel/react';
import 'notpixel/react.css';
import { createTracker } from 'notpixel/browser';
 
// Create tracker for impressions/clicks
const tracker = createTracker({
  baseURL: 'https://api.notpixel.ai',
  publisherId: 'pub_10565',
});
 
function MyComponent({ ad, impressionId }) {
  return (
    <AdCard
      ad={ad}
      impressionId={impressionId}
      tracker={tracker}
      onImpression={() => tracker.impression(impressionId)}
      onClick={() => tracker.click(impressionId)}
    />
  );
}

Components

Both components include Ocultar anúncio and Denunciar anúncio. Hide removes the current display; the same ad can be selected later. Report asks for a reason and optional details, then hides the ad after the server confirms receipt. Pass tracker when using a custom API URL. onHide and onReport notify the host application after each action.

AdCard

Compact card for sponsored suggestions in a conversation.

Sponsored Optimize Your Database — Speed up queries by 10x with intelligent indexing and caching. Learn More


<AdCard
  ad={ad}
  impressionId={impressionId}
  onImpression={() => {}}
  onClick={() => {}}
  className="custom-class"
/>

AdBanner

Horizontal banner for header/footer placements.


<AdBanner
  ad={ad}
  impressionId={impressionId}
  onImpression={() => {}}
  onClick={() => {}}
  className="custom-class"
/>

Props

Both components share the same props:

Prop	Type	Required	Description
`ad`	`Ad`	Yes	The ad object from SDK
`impressionId`	`string`	No	Impression ID for tracking, defaults to the ID on the ad
`onImpression`	`() => void`	No	Called when ad becomes visible
`onClick`	`() => void`	No	Called when CTA is clicked
`className`	`string`	No	Additional CSS classes

Auto Impression Tracking

Components automatically track impressions using IntersectionObserver:

Tracks when 50% of the ad is visible
Fires onImpression only once per mount
Falls back to immediate tracking if IntersectionObserver unavailable


<AdCard
  ad={ad}
  impressionId={impressionId}
  onImpression={() => {
    // Fires automatically when visible
    tracker.impression(impressionId);
  }}
/>

Full Example

Next.js App Router

app/chat/page.tsx


import Ads from 'notpixel';
import { AdCard } from 'notpixel/react';
import { AdTracker } from './ad-tracker';
 
export default async function ChatPage() {
  const ads = new Ads({
    publisherId: 'pub_10565',
    model: 'openai/gpt-5.2',
    input: 'Recommend tools for a React performance audit.',
  });
 
  // Fetch ad server-side
  const ad = await ads.getAd();
  const impressionId = 'imp_from_backend';
 
  if (!ad) return null;
 
  return (
    <div>
      {/* Chat content */}
      <AdTracker ad={ad} impressionId={impressionId} />
    </div>
  );
}

app/chat/ad-tracker.tsx


'use client';
 
import { AdCard } from 'notpixel/react';
import { createTracker } from 'notpixel/browser';
import type { Ad } from 'notpixel/react';
 
const tracker = createTracker({
  baseURL: 'https://api.notpixel.ai',
  publisherId: 'pub_10565',
});
 
export function AdTracker({ ad, impressionId }: { ad: Ad; impressionId: string }) {
  return (
    <AdCard
      ad={ad}
      impressionId={impressionId}
      onImpression={() => tracker.impression(impressionId)}
      onClick={() => tracker.click(impressionId)}
      className="max-w-sm"
    />
  );
}

AdCard and AdBanner automatically confirm pending production opportunities from the verified website. The CTA becomes active once the API confirms the impression. Custom integrations can override the callback with onViewQualified(opportunityId).

Customizing Styles

Override Classes

Pass your own class and override the card tokens in your stylesheet:


<AdCard
  ad={ad}
  impressionId={impressionId}
  className="my-sponsored-card"
/>

Default styles

AdCard uses the compact rectangular campaign preview. Its scoped stylesheet supports .dark and [data-theme="dark"] on an ancestor. The className prop and the card’s CSS custom properties let you tune the default layout.

AdBanner continues to use Tailwind classes:

Container: flex items-center bg-gray-50 border border-gray-200 rounded-xl dark:bg-gray-950/50 dark:border-gray-800/50
Disclosure: text-xs text-gray-500 uppercase dark:text-gray-400
Headline: font-medium text-gray-900 dark:text-white
Body: text-sm text-gray-500 dark:text-gray-400
CTA: bg-gradient-to-r from-purple-500 via-pink-500 to-orange-500 text-white rounded-md

Data Attributes

Components include data attributes for custom tracking:


<div data-ad-id="ad-123" data-impression-id="imp-456">
  ...
</div>

TypeScript

Import types from the react entry:


import type { Ad, AdCardProps, AdBannerProps } from 'notpixel/react';