Skip to main content

​
React SDK API Reference

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

​
Components

​
SuperflagProvider

Context provider that wraps your app and manages flag state. 
<SuperflagProvider clientKey="pub_..." ttlSeconds={60}>
  <App />
</SuperflagProvider>
Props:
PropTypeRequiredDefaultDescription
clientKeystringNoenv varPublic client key (pub_*)
ttlSecondsnumberNo60Cache TTL in seconds
storageStorageAdapterNolocalStorageCustom storage adapter
childrenReactNodeYes-React children
Environment Variable Fallback: If clientKey is not provided, the provider looks for:
  • process.env.NEXT_PUBLIC_SUPERFLAG_CLIENT_KEY (Next.js)
  • import.meta.env.VITE_SUPERFLAG_CLIENT_KEY (Vite)
  • process.env.REACT_APP_SUPERFLAG_CLIENT_KEY (CRA)

​
Hooks

​
useFlag

Get the value of a feature flag with type safety. 
const value = useFlag<T>(name: string, fallback?: T): T | undefined
Parameters:
ParameterTypeRequiredDescription
namestringYesFlag key name
fallbackTNoDefault value if flag not found
Returns: The flag value cast to type 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
Returns:
FieldTypeDescription
flagsFlagsAll flags as key-value pairs
statusSuperflagStatusCurrent SDK status
readybooleanShorthand for status === 'ready'
loadingbooleanShorthand for status === 'loading'
versionnumber | nullConfig version number
etagstring | nullETag from last fetch
lastFetchedAtnumber | nullTimestamp of last fetch
errorstring | nullError message if failed
Example: 
function MyComponent() {
  const { ready, loading, error, flags } = useFlags()

  if (loading) return <Spinner />
  if (error) return <Error message={error} />
  if (!ready) return null

  return <div>Loaded {Object.keys(flags).length} flags</div>
}

​
Types

​
SuperflagStatus

type SuperflagStatus = "idle" | "loading" | "ready" | "error" | "rate-limited"
StatusDescription
idleInitial state before fetching
loadingFetching flags from API
readyFlags loaded successfully
errorFailed to load flags
rate-limitedMonthly 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
}

​
StorageAdapter

Custom storage adapter interface for persisting flags. 
interface StorageAdapter {
  getItem(key: string): Promise<string | null>
  setItem(key: string, value: string): Promise<void>
  removeItem(key: string): Promise<void>
}
Example Implementation: 
const sessionStorageAdapter: StorageAdapter = {
  async getItem(key) {
    return sessionStorage.getItem(key)
  },
  async setItem(key, value) {
    sessionStorage.setItem(key, value)
  },
  async removeItem(key) {
    sessionStorage.removeItem(key)
  }
}

​
SuperflagProviderProps

interface SuperflagProviderProps {
  clientKey?: string
  ttlSeconds?: number
  storage?: StorageAdapter
  children: React.ReactNode
}

​
Constants

​
Cache Key

The SDK stores cached config under this localStorage key: 
const CACHE_KEY = "superflag:cache:v1"

​
Exports

All exports from @superflag-sh/react: 
// Components
export { SuperflagProvider }

// Hooks
export { useFlag, useFlags }

// Types
export type {
  SuperflagStatus,
  SuperflagState,
  SuperflagProviderProps,
  StorageAdapter,
  Flags,
  FlagValue,
  FlagType
}

​
TypeScript Usage

The SDK is fully typed. Import types alongside runtime exports: 
import {
  SuperflagProvider,
  useFlag,
  useFlags,
  type SuperflagState,
  type StorageAdapter
} from '@superflag-sh/react'

​
Next Steps

Usage Guide

Learn how to use the SDK

Examples

Common patterns and recipes