React Native SDK API Reference
Complete reference for all exports, types, and interfaces in @superflag-sh/react-native.
The React Native SDK has the same API as the React (web) SDK, but uses AsyncStorage instead of localStorage.
Components
SuperflagProvider
Context provider that wraps your app and manages flag state.
<SuperflagProvider clientKey="pub_..." ttlSeconds={60}>
<App />
</SuperflagProvider>
| Prop | Type | Required | Default | Description |
|---|
clientKey | string | No | env var | Public client key (pub_*) |
ttlSeconds | number | No | 60 | Cache TTL in seconds |
children | ReactNode | Yes | - | React children |
clientKey is not provided, the provider looks for:
process.env.EXPO_PUBLIC_SUPERFLAG_CLIENT_KEY (Expo)
Hooks
useFlag
Get the value of a feature flag with type safety.
const value = useFlag<T>(name: string, fallback?: T): T | undefined
| Parameter | Type | Required | Description |
|---|
name | string | Yes | Flag key name |
fallback | T | No | Default value if flag not found |
T, or fallback if provided, or undefined.
Examples:
// Boolean flag
const enabled = useFlag('feature-enabled', false)
// String flag
const theme = useFlag<string>('theme', 'light')
// Number flag
const limit = useFlag<number>('rate-limit', 100)
// JSON flag
const config = useFlag<{ api: string }>('api-config', { api: '/v1' })
useFlags
Get the current SDK state.
const state = useFlags(): SuperflagState
| Field | Type | Description |
|---|
flags | Flags | All flags as key-value pairs |
status | SuperflagStatus | Current SDK status |
ready | boolean | Shorthand for status === 'ready' |
loading | boolean | Shorthand for status === 'loading' |
version | number | null | Config version number |
etag | string | null | ETag from last fetch |
lastFetchedAt | number | null | Timestamp of last fetch |
error | string | null | Error message if failed |
import { useFlags } from '@superflag-sh/react-native'
import { ActivityIndicator, Text, View } from 'react-native'
function MyScreen() {
const { ready, loading, error, flags } = useFlags()
if (loading) return <ActivityIndicator />
if (error) return <Text>Error: {error}</Text>
if (!ready) return <View />
return <Text>Loaded {Object.keys(flags).length} flags</Text>
}
Types
SuperflagStatus
type SuperflagStatus = "idle" | "loading" | "ready" | "error" | "rate-limited"
| Status | Description |
|---|
idle | Initial state before fetching |
loading | Fetching flags from API |
ready | Flags loaded successfully |
error | Failed to load flags |
rate-limited | Monthly quota exceeded |
SuperflagState
interface SuperflagState {
flags: Flags
status: SuperflagStatus
version: number | null
etag: string | null
lastFetchedAt: number | null
error: string | null
}
Flags
type Flags = Record<string, FlagValue>
interface FlagValue {
type: "bool" | "string" | "number" | "json"
value: boolean | string | number | object
}
SuperflagProviderProps
interface SuperflagProviderProps {
clientKey?: string
ttlSeconds?: number
children: React.ReactNode
}
Constants
Cache Key
The SDK stores cached config under this AsyncStorage key:
const CACHE_KEY = "superflag:cache:v1"
Exports
All exports from @superflag-sh/react-native:
// Components
export { SuperflagProvider }
// Hooks
export { useFlag, useFlags }
// Types
export type {
SuperflagStatus,
SuperflagState,
SuperflagProviderProps,
Flags,
FlagValue,
FlagType
}
Differences from React (Web) SDK
The React Native SDK differs from the React SDK in these ways:
| Feature | React SDK | React Native SDK |
|---|
| Storage | localStorage | AsyncStorage |
| Custom storage prop | ✅ Supported | ❌ Not supported |
| Browser APIs | Assumes available | Checks existence first |
| Bundle output | Any bundler | Must use tsc |
TypeScript Usage
The SDK is fully typed. Import types alongside runtime exports:
import {
SuperflagProvider,
useFlag,
useFlags,
type SuperflagState
} from '@superflag-sh/react-native'
Next Steps
