> ## Documentation Index
> Fetch the complete documentation index at: https://superflag.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Complete API documentation for the React Native SDK

# React Native SDK API Reference

Complete reference for all exports, types, and interfaces in `@superflag-sh/react-native`.

<Note>
  The React Native SDK has the same API as the React (web) SDK, but uses AsyncStorage instead of localStorage.
</Note>

## Components

### SuperflagProvider

Context provider that wraps your app and manages flag state.

```tsx theme={null}
<SuperflagProvider clientKey="pub_..." ttlSeconds={60}>
  <App />
</SuperflagProvider>
```

**Props:**

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

**Environment Variable Fallback:**

If `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.

```tsx theme={null}
const value = useFlag<T>(name: string, fallback?: T): T | undefined
```

**Parameters:**

| Parameter  | Type     | Required | Description                     |
| ---------- | -------- | -------- | ------------------------------- |
| `name`     | `string` | Yes      | Flag key name                   |
| `fallback` | `T`      | No       | Default value if flag not found |

**Returns:**

The flag value cast to type `T`, or `fallback` if provided, or `undefined`.

**Examples:**

```tsx theme={null}
// 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.

```tsx theme={null}
const state = useFlags(): SuperflagState
```

**Returns:**

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

**Example:**

```tsx theme={null}
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

```tsx theme={null}
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

```tsx theme={null}
interface SuperflagState {
  flags: Flags
  status: SuperflagStatus
  version: number | null
  etag: string | null
  lastFetchedAt: number | null
  error: string | null
}
```

### Flags

```tsx theme={null}
type Flags = Record<string, FlagValue>

interface FlagValue {
  type: "bool" | "string" | "number" | "json"
  value: boolean | string | number | object
}
```

### SuperflagProviderProps

```tsx theme={null}
interface SuperflagProviderProps {
  clientKey?: string
  ttlSeconds?: number
  children: React.ReactNode
}
```

## Constants

### Cache Key

The SDK stores cached config under this AsyncStorage key:

```tsx theme={null}
const CACHE_KEY = "superflag:cache:v1"
```

## Exports

All exports from `@superflag-sh/react-native`:

```tsx theme={null}
// 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:

```tsx theme={null}
import {
  SuperflagProvider,
  useFlag,
  useFlags,
  type SuperflagState
} from '@superflag-sh/react-native'
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Usage Guide" icon="code" href="/react-native/usage">
    Learn how to use the SDK in your app
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/react-native/troubleshooting">
    Common issues and solutions
  </Card>
</CardGroup>