React AI ads SDK.
Drop-in React components to show Surfacedd sponsored results inside your AI app. Works with Create React App, Vite, and any React 18+ stack.
Install
npm install @surfacedd/react
Import
import { SurfaceddProvider, SponsoredAnswer } from '@surfacedd/react'Initialize
<SurfaceddProvider appId="app_xxx">
{children}
</SurfaceddProvider>Fetch a sponsored answer
<SponsoredAnswer context={{ query: userMessage }} />Features
- SurfaceddProvider context with React 18 streaming support
- SponsoredAnswer and DisplayBanner components
- Hook API: useSurfacedd() for custom UI
- Zero runtime overhead when no matching ad
- 60/40 developer revenue share
Install in three steps
- Install. Run npm install @surfacedd/react in your React project. The package supports tree-shaking; only the components you import land in your bundle.
- Wrap your app. Wrap your root component with SurfaceddProvider and pass your app ID. Get your app ID from the Surfacedd dashboard after joining the waitlist.
- Render sponsored answers. Drop SponsoredAnswer inside your chat message UI and pass the user query as context. The component handles ad matching, disclosure labeling, and click tracking automatically.
Frequently asked questions
Which React versions does the SDK support?
The @surfacedd/react package supports React 18 and 19, including Server Components, Suspense, and the new use() hook. For React 17 and earlier, use the vanilla JavaScript SDK via @surfacedd/web.
Does it work with Next.js?
Yes. For Next.js specifically we recommend the dedicated /sdk/vercel-ai-sdk path which integrates natively with the Vercel AI SDK. The React SDK works inside Next.js Client Components.
How do I test ads without a live AI app?
Initialize the SDK in test mode by passing testMode: true to the provider. Ads return deterministic mock responses so your Jest, Vitest, or Playwright tests are reproducible.
Related SDKs
Ready to ship ads in your React app?
Join the waitlist for SDK access. 60% revenue share, no minimums, no contracts.