React SDK

The official React SDK for Flagpool. Provides hooks and components for evaluating feature flags in React and Next.js applications.

Installation

npm install @flagpool/react

This package includes @flagpool/sdk as a dependency — no need to install it separately.

Quick Start

1. Wrap Your App with the Provider

import { FlagpoolProvider } from '@flagpool/react'

function App() {
  return (
    <FlagpoolProvider
      projectId="your-project-uuid"
      apiKey="your-api-key"
      decryptionKey="your-decryption-key"
      context={{ userId: 'user-123', plan: 'pro' }}
    >
      <MyApp />
    </FlagpoolProvider>
  )
}

2. Use Hooks in Your Components

import { useFlag, useFlagValue } from '@flagpool/react'

function MyComponent() {
  const showNewFeature = useFlag('new-feature')
  const buttonColor = useFlagValue('cta-button-color', 'blue')

  return (
    <div>
      {showNewFeature && <NewFeature />}
      <Button color={buttonColor}>Click me</Button>
    </div>
  )
}

Provider Props

<FlagpoolProvider
  projectId="uuid-xxx" // Required
  apiKey="your-api-key" // Required
  decryptionKey="your-key" // Required
  context={{ userId: 'u1' }} // Optional: user context for targeting
  analytics={{ enabled: true }} // Optional: enable evaluation analytics
  pollingInterval={30000} // Optional: polling interval in ms
  streaming={true} // Optional: enable real-time updates
  cryptoAdapter={adapter} // Optional: for encrypted target lists
  onReady={() => {}} // Optional: called when flags are ready
  onError={(err) => {}} // Optional: called on initialization error
>
  <App />
</FlagpoolProvider>

Hooks

useFlag(flagKey, defaultValue?)

Returns a boolean feature flag value. The most common hook.

import { useFlag } from '@flagpool/react'

function MyComponent() {
  const isEnabled = useFlag('new-feature')
  const withDefault = useFlag('new-feature', false)

  return isEnabled ? <NewFeature /> : <OldFeature />
}

useFlagValue<T>(flagKey, defaultValue?)

Returns a flag value of any type — string, number, boolean, or object. Supports TypeScript generics.

import { useFlagValue } from '@flagpool/react'

function MyComponent() {
  const color = useFlagValue('button-color', 'blue')
  const limit = useFlagValue<number>('rate-limit', 100)
  const config = useFlagValue<FeatureConfig>('feature-config', defaultConfig)
}

useFlagDetails<T>(flagKey, defaultValue?)

Returns detailed flag information including loading and error states. Use this when you need to handle the loading phase explicitly.

import { useFlagDetails } from '@flagpool/react'

function MyComponent() {
  const { value, isReady, isLoading, error } = useFlagDetails('feature', false)

  if (isLoading) return <Spinner />
  if (error) return <ErrorMessage error={error} />

  return value ? <NewFeature /> : <OldFeature />
}

useFlagpool()

Access the Flagpool client and context directly. Useful for updating context after login or for debugging.

import { useFlagpool } from '@flagpool/react'

function UserLoader() {
  const { client, isReady, isLoading, error, setContext } = useFlagpool()
  const { user } = useAuth()

  useEffect(() => {
    if (user) {
      setContext({
        userId: user.id,
        email: user.email,
        plan: user.subscription.plan,
      })
    }
  }, [user, setContext])

  return <MainApp />
}

Components

<Feature>

Conditionally render content based on a boolean flag.

import { Feature } from '@flagpool/react'

// Simple usage
<Feature flag="new-checkout">
  <NewCheckout />
</Feature>

// With fallback
<Feature flag="new-checkout" fallback={<OldCheckout />}>
  <NewCheckout />
</Feature>

<Variant>

Render content when a flag matches a specific value. Ideal for A/B tests.

import { Variant } from '@flagpool/react'

<Variant flag="cta-color" value="blue">
  <BlueButton />
</Variant>
<Variant flag="cta-color" value="green">
  <GreenButton />
</Variant>

<FeatureWithLoading>

Feature component with built-in loading and error states.

import { FeatureWithLoading } from '@flagpool/react'

;<FeatureWithLoading
  flag="new-checkout"
  loading={<Spinner />}
  error={(err) => <ErrorMessage message={err.message} />}
  fallback={<OldCheckout />}
>
  <NewCheckout />
</FeatureWithLoading>

TypeScript Support

Full TypeScript support with generics for type-safe flag values:

interface FeatureConfig {
  maxItems: number
  theme: 'light' | 'dark'
}

const config = useFlagValue<FeatureConfig>('feature-config', {
  maxItems: 10,
  theme: 'light',
})

Server-Side Rendering (Next.js)

The provider handles hydration automatically. Flags show their default values during server render and update on the client once initialized.

For optimal SSR support, use useFlagDetails to handle the loading state:

function MyComponent() {
  const { value, isLoading } = useFlagDetails('feature', false)

  if (isLoading) return <DefaultView />

  return value ? <NewFeature /> : <OldFeature />
}

Place the provider in your root layout or a client wrapper component. Works with both the App Router and Pages Router.

Analytics

Enable opt-in evaluation analytics via the provider:

<FlagpoolProvider
  projectId="your-project-uuid"
  apiKey="your-api-key"
  decryptionKey="your-decryption-key"
  analytics={{
    enabled: true,
    flushInterval: 60000,
    flushThreshold: 100,
    sampleRate: 1.0,
  }}
>
  <App />
</FlagpoolProvider>

Option	Type	Default	Description
enabled	boolean	false	Enable/disable analytics
flushInterval	number	60000	Flush interval in ms (minimum: 30000)
flushThreshold	number	100	Flush after N evaluations
sampleRate	number	1.0	Sample rate (0.0–1.0)

Debugging in the Browser

console.log(__FLAGPOOL__.state.analytics)
console.log(__FLAGPOOL__.state.flags)
__FLAGPOOL__.flushAnalytics()

Next Steps

• JavaScript / TypeScript SDK — for server-side or non-React usage
• Getting Started — full setup guide