React SDK API Reference

Complete API reference for @supashiphq/react-sdk.

SupaProvider

The provider component that makes feature flags available to your React component tree.


<SupaProvider config={config}>{children}</SupaProvider>

Props:

Prop	Type	Required	Description
`config`	`SupaClientConfig`	Yes	Configuration for the client
`children`	`React.ReactNode`	Yes	Child components
`plugins`	`SupaPlugin[]`	No	Custom plugins
`toolbar`	`ToolbarConfig`	No	Development toolbar settings

Configuration Options:


import { FeaturesWithFallbacks } from '@supashiphq/react-sdk'
 
const config = {
  apiKey: 'your-api-key',
  environment: 'production',
  features: {
    // Required: define all feature flags with fallback values
    'my-feature': false,
    config: { theme: 'light' },
  } satisfies FeaturesWithFallbacks,
  context: {
    // Optional: targeting context
    userID: 'user-123',
    email: '[email protected]',
    plan: 'premium',
  },
  networkConfig: {
    // Optional: network settings
    featuresAPIUrl: 'https://api.supashiphq.com/features',
    retry: {
      enabled: true,
      maxAttempts: 3,
      backoff: 1000,
    },
    requestTimeoutMs: 5000,
  },
}

Supported Feature Value Types:

Type	Example	Description
`boolean`	`false`	Simple on/off flags
`object`	`{ theme: 'dark', showLogo: true }`	Configuration objects
`array`	`['feature-a', 'feature-b']`	Lists of values
`null`	`null`	Disabled/unavailable flag

Note: Strings and numbers are not supported as standalone feature values. Use objects instead: { value: 'string' } or { value: 42 }.

useFeature Hook

Retrieves a single feature flag value with React state management and full TypeScript type safety.


const result = useFeature(featureName, options?)

Parameters:

featureName: string - The feature flag key
options?: object
- context?: Record<string, unknown> - Context override for this request
- shouldFetch?: boolean - Whether to fetch the feature (default: true)

Return Value:


{
  feature: T | null,        // The feature value (typed based on your Features interface)
  isLoading: boolean,       // Loading state
  isSuccess: boolean,       // Success state
  isError: boolean,         // Error state
  error: Error | null,      // Error object if failed
  status: 'idle' | 'loading' | 'success' | 'error',
  refetch: () => void,      // Function to manually refetch
  // ... other query state properties
}

Examples:


function MyComponent() {
  // Simple boolean feature
  const { feature: isEnabled, isLoading } = useFeature('new-ui')
 
  if (isLoading) return <Skeleton />
 
  return <div>{isEnabled ? <NewUI /> : <OldUI />}</div>
}
 
function ConfigComponent() {
  // Object feature
  const { feature: config } = useFeature('theme-config')
 
  if (!config) return null
 
  return (
    <div className={config.theme}>
      {config.showLogo && <Logo />}
      <div style={{ color: config.primaryColor }}>Content</div>
    </div>
  )
}
 
function ConditionalFetch() {
  const { user, isLoading: userLoading } = useUser()
 
  // Only fetch when user is loaded
  const { feature } = useFeature('user-specific-feature', {
    context: { userId: user?.id },
    shouldFetch: !userLoading && !!user,
  })
 
  return <div>{feature && <SpecialContent />}</div>
}

useFeatures Hook

Retrieves multiple feature flags in a single request with type safety.


const result = useFeatures(featureNames, options?)

Parameters:

featureNames: readonly string[] - Array of feature flag keys
options?: object
- context?: Record<string, unknown> - Context override for this request
- shouldFetch?: boolean - Whether to fetch features (default: true)

Return Value:


{
  features: { [key: string]: T | null },  // Object with feature values (typed based on keys)
  isLoading: boolean,
  isSuccess: boolean,
  isError: boolean,
  error: Error | null,
  status: 'idle' | 'loading' | 'success' | 'error',
  refetch: () => void,
  // ... other query state properties
}

Examples:


function Dashboard() {
  const { user } = useUser()
 
  // Fetch multiple features at once (more efficient than multiple useFeature calls)
  const { features, isLoading } = useFeatures(
    ['new-dashboard', 'beta-mode', 'show-sidebar'],
    {
      context: {
        userId: user?.id,
        plan: user?.plan,
      },
    },
  )
 
  if (isLoading) return <LoadingSpinner />
 
  return (
    <div className={features['new-dashboard'] ? 'new-layout' : 'old-layout'}>
      {features['show-sidebar'] && <Sidebar />}
      {features['beta-mode'] && <BetaBadge />}
      <MainContent />
    </div>
  )
}
 
function FeatureList() {
  // TypeScript will infer the correct types for each feature
  const { features } = useFeatures(['feature-a', 'feature-b', 'config-feature'])
 
  return (
    <div>
      {features['feature-a'] && <FeatureA />}
      {features['feature-b'] && <FeatureB />}
      {features['config-feature'] && (
        <ConfigDisplay config={features['config-feature']} />
      )}
    </div>
  )
}

useFeatureContext Hook

Access and update the feature context within components.


const { context, updateContext } = useFeatureContext()

Example:


function UserProfileSettings() {
  const { context, updateContext } = useFeatureContext()
  const [user, setUser] = useState(null)
 
  const handleUserUpdate = newUser => {
    setUser(newUser)
 
    // Update feature context when user changes
    // This will trigger refetch of all features
    updateContext({
      userId: newUser.id,
      plan: newUser.subscriptionPlan,
      segment: newUser.segment,
    })
  }
 
  return <form onSubmit={handleUserUpdate}>{/* User profile form */}</form>
}

useClient Hook

Access the underlying SupaClient instance for advanced use cases.


const client = useClient()
 
// Use client methods directly
const feature = await client.getFeature('my-feature', { context: { ... } })
const features = await client.getFeatures(['feature-1', 'feature-2'])