> ## 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.

# React Native SDK

> Render Gravity ads natively in React Native apps.

## Install

```bash theme={null}
npm install @gravity-ai/react-native
```

`react` (>=18.2) and `react-native` (>=0.76) are peer dependencies. The package has no DOM or `react-dom` dependency.

## Request ads

Request ads from your server with the [JavaScript SDK](/sdks/javascript). Spread `GRAVITY_RN_SPEC_OPTIONS` into the request so Gravity returns placement designs the native renderer can paint:

```ts theme={null}
import { GRAVITY_RN_SPEC_OPTIONS } from '@gravity-ai/react-native';

const result = await gravity.getAds(req, messages, placements, {
  ...GRAVITY_RN_SPEC_OPTIONS,
});
```

## Render ads

Pass the ad returned by Gravity to `GravityAd`:

```tsx theme={null}
import { GravityAd, GravityThemeProvider } from '@gravity-ai/react-native';

export function ChatResponse({ response, ads }) {
  return (
    <GravityThemeProvider>
      <Text>{response}</Text>
      {ads[0] && <GravityAd ad={ads[0]} />}
    </GravityThemeProvider>
  );
}
```

`GravityAd` automatically handles the placement design, fallback, impression and click tracking, disclosure, and light and dark themes. The impression fires once when at least 50% of the ad is visible.

## Visibility in lists

In a virtualized list (`FlatList`, `SectionList`), pass viewability from `onViewableItemsChanged` so the impression fires exactly when the list reports the ad visible:

```tsx theme={null}
<GravityAd ad={ad} isViewable={viewableAdIds.has(ad.id)} />
```

In a plain `ScrollView`, no wiring is required — visibility is measured automatically. Publishers who drive visibility from their own `onScroll` handler can use the `measureVisibility` callback returned by `useAdTracking`.

## Theming

`GravityThemeProvider` follows the device color scheme by default. Override semantic tokens as needed:

```tsx theme={null}
<GravityThemeProvider theme={{ primary: '#6d28d9' }}>
```