SDK (React Native)

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

Package: @hatched/react-native

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. 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/react-native builds on @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.