# SDK (React Native)

> Component and hook reference for @hatched/react-native — HatchedProvider, the native widgets, HatchedWebView, and hooks.

Source: https://docs.hatched.live/docs/reference/react-native

Package: [`@hatched/react-native`](https://npmjs.com/package/@hatched/react-native)

```bash
npx expo install @hatched/react-native
# optional peers
npx expo install react-native-webview react-native-svg
```

For the end-to-end walkthrough (tokens, theming, WebView fallback, pitfalls) see
[React Native integration](/docs/guides/react-native-integration). This page is
the API surface.

## `<HatchedProvider>`

Owns the shared data layer and must wrap every widget and hook.

| Prop | Type | Required | Notes |
| --- | --- | --- | --- |
| `token` | `string` | yes | Widget session token or read-only embed token (server-minted). |
| `apiBaseUrl` | `string` | yes | e.g. `https://api.hatched.live/api/v1`. |
| `theme` | `'light' \| 'dark'` | no | Initial mode; the live `/widget/theme` palette/personality overrides it. |
| `lang` | `string` | no | UI language hint (defaults to English). |
| `pollIntervalMs` | `number` | no | Base `/widget/state` poll interval. |
| `onCelebrate` | `(event) => void` | no | Fired on badge / evolution / streak celebrations. |

The provider polls `/widget/state`, pauses while the app is backgrounded
(`AppState`), honors the OS reduced-motion setting, and re-resolves the theme on
foreground.

## Widgets

All widgets accept an optional `style` prop and must render inside
`<HatchedProvider>`.

| Component | Props | Surface |
| --- | --- | --- |
| `BuddyWidget` | `allowRadar?: boolean` | Buddy image, name, coins, skills (bars or SVG radar), badge/rank counters, evolution-ready hint. |
| `LeaderboardWidget` | `scope?: 'global' \| 'team'`, `viewMode?: 'top' \| 'around_me' \| 'hybrid'`, `limit?: number` | Ranked board with the current player highlighted. |
| `MarketplaceWidget` | — | Browse, buy, equip. CTAs are scope-gated. |
| `StreakWidget` | `streakKey?: string` | Current streak, best, next milestone. |
| `BadgesWidget` | — | Earned badges + earned/total counter. |
| `TokensWidget` | — | Primary balance + capped progression tokens. |
| `PathWidget` | `pathKey?: string` | Journey steps/sub-steps; tappable optimistic completion. |

`StreakWidget`, `PathWidget`, and `LeaderboardWidget` fetch their own endpoint;
the rest read state hydrated by the provider's `/widget/state` poll.

## `<HatchedWebView>`

Renders a Hatched widget through the production CDN loader for the surfaces not
reimplemented natively.

| Prop | Type | Notes |
| --- | --- | --- |
| `widget` | `string` | One of `kudos`, `group-quest`, `feed`, `mystery-box`, `league`, `council`, `hexad-survey`, `celebrate`. Required. |
| `token` | `string` | Falls back to the provider. |
| `apiBaseUrl` | `string` | Falls back to the provider. |
| `theme` | `'light' \| 'dark'` | Falls back to the provider's mode, else `light`. |
| `cdnBaseUrl` | `string` | Loader origin; defaults to `https://cdn.hatched.live`. |
| `onEvent` | `(name, payload?) => void` | `ready` / `effects` from the bridge. |
| `onCelebrate` | `(event) => void` | Celebration events from the widget. |
| `syncStore` | `boolean` | Forward `track` effects into the provider's store (default `true`). |

Requires the `react-native-webview` peer. The token is injected after load
(never in the HTML); the loader's bridge forwards effects/celebrations back to
the shared store.

## Hooks

| Hook | Returns |
| --- | --- |
| `useTrack()` | `(type: string, properties?: Record<string, unknown>) => Promise<TrackResult \| null>` |
| `useHatched()` | `{ store, token, apiBaseUrl, ready, track, refresh }` |
| `useTheme()` | the resolved `ResolvedTheme` |
| `useWorkspaceState()` | the full `WorkspaceState` (re-renders on change) |
| `useWorkspaceStore(selector)` | `selector(WorkspaceState)`, re-rendered on change |

## Optional peers

| Peer | Needed for | Without it |
| --- | --- | --- |
| `react-native-webview` | `<HatchedWebView>` | Mounting it throws a clear install error. |
| `react-native-svg` | Buddy skill radar | Buddy widget falls back to skill bars. |
| `@react-native-async-storage/async-storage` | Persisting ceremony-seen state | Falls back to in-memory. |

## `@hatched/widget-core`

`@hatched/react-native` builds on
[`@hatched/widget-core`](https://npmjs.com/package/@hatched/widget-core) — the
headless, render-free core (workspace store, smart-poll, fetch/auth, theme
resolution, shared types) that also powers the web widgets. You normally consume
it transitively; install it directly only if you build a custom renderer. The
commonly needed types (`ResolvedTheme`, `WorkspaceState`, `BuddyData`,
`TokensPayload`, …) are re-exported from `@hatched/react-native`.