> ## 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.
# Server-rendered ads
> React components that render Gravity ads from a server-delivered spec — ship new ad designs with no publisher code change or SDK upgrade.
## Installation
```bash theme={null}
npm install @gravity-ai/ui
```
Set `GRAVITY_API_KEY` in your server environment.
## How the pieces fit together
Place `` where the ad should appear. For a ShadCN/Tailwind app that's the entire integration.
On mount, `GravityAd` measures its container with a `ResizeObserver`, sends the dimensions to the engine, and fetches the ad for the placement.
The engine returns the ad object with a `renderer_spec`: a JSON layout tree describing the full unit. We can change that spec server-side at any time.
The SDK's runtime interprets the spec into DOM, fires the impression pixel on visibility, and routes clicks through the tracked URL.
Because the layout lives in the response, Gravity ships a new ad design from the server — no publisher code change, no SDK upgrade.
## Render ads
```tsx theme={null}
import { GravityAd } from '@gravity-ai/ui';
function ChatResponse({ response }) {
return (
);
}
```
| Prop | Type | Description |
| -------------------------------- | ---------------- | -------------------------------------------------------------------------------------------- |
| `placement` | `string` | Placement identifier (required). |
| `apiKey` | `string` | Publisher API key. Defaults to `GRAVITY_API_KEY`. |
| `ad` | `GravityAdData` | Pass ad data directly instead of fetching. |
| `variant` | `GravityVariant` | Hard-pin a bundled layout, overriding the server spec. Omit to let Gravity drive the render. |
| `query` | `string` | User query/context for contextual serving. |
| `sessionId` | `string` | Stable session ID so a user sees a consistent render within a session. |
| `showLabel` | `boolean` | Show the "Ad"/sponsored label. |
| `onLoad` / `onEmpty` / `onClick` | callbacks | Lifecycle hooks. `onLoad` includes measured dimensions. |
The component handles impression tracking automatically via `IntersectionObserver`.
## Theme
ShadCN/Tailwind apps need nothing — the ad reads their existing CSS variables and follows light/dark mode. Other apps wrap once with `GravityThemeProvider`:
```tsx theme={null}
import { GravityThemeProvider } from '@gravity-ai/ui';
```
## Renderer spec
The ad response carries a `renderer_spec` — the JSON tree the SDK renders. Render precedence:
1. Publisher `variant` prop — a hard pin. Always wins.
2. Server `renderer_spec` — the normal path. Gravity ships the look remotely.
3. Bundled fallback — the SDK's built-in, dimension-aware look. Used only when neither above is present, so the unit always renders something sensible with zero config.
Whether an ad response carries a `renderer_spec` at all is decided server-side, per placement: Gravity attaches the spec when the placement has a default design configured on our end. There is no request parameter to enable it — see [how to get one set up](#want-a-custom-default-look-for-your-placement).
A spec for a single line of text:
```json theme={null}
{
"version": 1,
"name": "text-line",
"root": {
"type": "link",
"style": { "display": "inline", "fontSize": "14px", "color": "hsl(var(--muted-foreground))" },
"children": [
{ "type": "text", "text": "↗ ", "style": { "color": "hsl(var(--primary))", "fontWeight": 600 } },
{ "type": "text", "bind": "title", "style": { "color": "hsl(var(--foreground))", "fontWeight": 500 } },
{ "type": "text", "bind": "cta", "style": { "color": "hsl(var(--primary))", "fontWeight": 600 } }
]
}
}
```
### Node types
| `type` | Renders as | Notes |
| ------- | ---------- | ------------------------------------------------------------ |
| `box` | `