> ## 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.
# Usage
> Learn how to use feature flags in your React application
# React SDK Usage
Learn how to integrate Superflag into your React web application.
## Setup Provider
Wrap your app with `SuperflagProvider` at the root level:
```tsx Next.js App Router theme={null}
// app/layout.tsx
import { SuperflagProvider } from '@superflag-sh/react'
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
{children}
)
}
```
```tsx Next.js Pages Router theme={null}
// pages/_app.tsx
import { SuperflagProvider } from '@superflag-sh/react'
import type { AppProps } from 'next/app'
export default function App({ Component, pageProps }: AppProps) {
return (
)
}
```
```tsx Vite / CRA theme={null}
// main.tsx or index.tsx
import { SuperflagProvider } from '@superflag-sh/react'
function App() {
return (
)
}
```
## Using Flags
### Basic Usage
Use the `useFlag` hook to access flag values:
```tsx theme={null}
import { useFlag } from '@superflag-sh/react'
function MyComponent() {
const showNewFeature = useFlag('new-feature', false)
return (
{showNewFeature && }
)
}
```
### Type-Safe Flags
Use TypeScript generics for type-safe flag values:
```tsx theme={null}
import { useFlag } from '@superflag-sh/react'
function ThemeSelector() {
// Boolean flag
const darkMode = useFlag('dark-mode', false)
// String flag
const theme = useFlag('theme', 'light')
// Number flag
const maxItems = useFlag('max-items', 10)
// JSON flag
const config = useFlag<{ color: string; size: number }>('ui-config', {
color: 'blue',
size: 14
})
return Theme: {theme}
}
```
### Checking SDK Status
Use `useFlags` to check if the SDK is ready:
```tsx theme={null}
import { useFlags } from '@superflag-sh/react'
function MyComponent() {
const { ready, loading, status, error } = useFlags()
if (loading) {
return Loading flags...
}
if (error) {
return Error: {error}
}
if (!ready) {
return Initializing...
}
return Flags loaded!
}
```
## Provider Props
Configure the provider with these optional props:
| Prop | Type | Default | Description |
| ------------ | ---------------- | -------------- | ----------------------------- |
| `clientKey` | `string` | env var | Public client key (`pub_*`) |
| `ttlSeconds` | `number` | `60` | Cache time-to-live in seconds |
| `storage` | `StorageAdapter` | `localStorage` | Custom storage adapter |
### Custom TTL
Control how long flags are cached:
```tsx theme={null}
// Cache for 5 minutes
```
### Custom Storage
Provide a custom storage adapter for specialized use cases:
```tsx theme={null}
import { SuperflagProvider } from '@superflag-sh/react'
const customStorage = {
async getItem(key: string): Promise {
return sessionStorage.getItem(key)
},
async setItem(key: string, value: string): Promise {
sessionStorage.setItem(key, value)
},
async removeItem(key: string): Promise {
sessionStorage.removeItem(key)
}
}
function App() {
return (
)
}
```
## Caching Behavior
The SDK uses smart ETag-based caching to minimize bandwidth:
1. **First load**: Fetches flags from API, stores in localStorage
2. **Subsequent loads**:
* Shows cached flags immediately
* Checks for updates in background using ETag
* Only downloads if config changed (HTTP 304 if unchanged)
3. **Cache expiry**: After `ttlSeconds`, forces a fresh fetch
This means your app loads instantly with cached flags while staying up-to-date in the background.
## Environment Variables
### Next.js
```bash .env.local theme={null}
NEXT_PUBLIC_SUPERFLAG_CLIENT_KEY=pub_prod_...
```
### Vite
```bash .env theme={null}
VITE_SUPERFLAG_CLIENT_KEY=pub_prod_...
```
### Create React App
```bash .env theme={null}
REACT_APP_SUPERFLAG_CLIENT_KEY=pub_prod_...
```
Always use **public keys** (`pub_*`) in client-side code. Never use server keys (`sdk_*`).
## Status Values
The `status` field from `useFlags()` can be:
| 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 |
## Error Handling
The SDK never crashes your app. Errors are returned in the state:
```tsx theme={null}
function MyComponent() {
const { status, error } = useFlags()
if (status === 'error') {
console.error('Failed to load flags:', error)
// App continues with fallback values
}
if (status === 'rate-limited') {
console.warn('Rate limited - using cached flags')
}
// Your component code...
}
```
## Next Steps
Complete type definitions and exports
Common patterns and use cases