@flagdeck/react NPM

Flagdeck React SDK

Overview

The Flagdeck React SDK provides integration of the Flagdeck feature flag system with React applications. It allows you to easily implement feature flags, A/B testing, and targeted rollouts in your React apps.

Installation

npm install @flagdeck/react
# or
yarn add @flagdeck/react
# Using pnpm
pnpm add @flagdeck/react

Quick Start

Wrap your app with the FlagdeckProvider to start using feature flags in your components:

import React from 'react';
import { FlagdeckProvider } from '@flagdeck/react';

function App() {
  return (
    <FlagdeckProvider
      options={{
        apiKey: 'YOUR_API_KEY',
        debug: true,
        realTimeUpdates: true,
      }}
      context={{               // Targeting context for flag evaluation
        userId: 'user-123',
        attributes: {
          country: 'US',
          plan: 'premium'
        }
      }}
    >
      <YourApp />
    </FlagdeckProvider>
  );
}

Then use one of our hooks or components to check feature flags:

import { useFlag } from '@flagdeck/react';

function FeatureComponent() {
  const { isEnabled, isLoading } = useFlag('new-feature');

  if (isLoading) {
    return <div>Loading...</div>;
  }

  return (
    <div>
      {isEnabled ? (
        <p>New feature is enabled!</p>
      ) : (
        <p>New feature is disabled.</p>
      )}
    </div>
  );
}

Core Components

`<FlagdeckProvider />`

The root provider component to initialize the SDK and provide flag data to all child components.

Props

Prop	Type	Description
`options`	`FlagdeckOptions`	Configuration options for the SDK
`context`	`Partial<EvaluationContext>`	Targeting context for flag evaluation
`readyDelayMs`	`number`	Optional delay before components can access flags
`children`	`ReactNode`	React children

`<FeatureFlag />`

Component for conditional rendering based on flag state:

<FeatureFlag
  flagKey="new-feature"
  fallback={<p>Feature disabled</p>}
>
  <p>Feature enabled!</p>
</FeatureFlag>

`<WithFeature />`

Render prop component for more flexible control:

<WithFeature flagKey="premium-dashboard">
  {({ isEnabled, isLoading }) => (
    isLoading ? (
      <div>Loading...</div>
    ) : isEnabled ? (
      <PremiumDashboard />
    ) : (
      <UpgradeBanner />
    )
  )}
</WithFeature>

`<FlagValue />`

Component to access and render specific flag values:

<FlagValue flagKey="theme-color" defaultValue="blue">
  {({ value, isLoading }) => (
    <div style={{ backgroundColor: value }}>
      Theme color: {value}
    </div>
  )}
</FlagValue>

Hooks

`useFlag(flagKey, defaultValue)`

Hook to check if a feature flag is enabled:

const { isEnabled, isLoading, error } = useFlag('new-feature', false);

`useFlagValue(flagKey, defaultValue)`

Hook to get the specific value of a feature flag:

const { value, isLoading, error } = useFlagValue('theme-color', 'blue');

`useFlags(flagKeys, defaultValue)`

Hook to check multiple flags at once:

const { values, isLoading, errors } = useFlags(['feature-a', 'feature-b'], false);
// values = { 'feature-a': true, 'feature-b': false }

`useFlagdeck()`

Hook to access the Flagdeck client instance and context:

const { client, isReady, error, context, setContext } = useFlagdeck();

// Update the context at runtime
setContext({
  userId: 'user-456',
  attributes: {
    plan: 'enterprise'
  }
});

Real-time Updates

The SDK supports real-time flag updates using Server-Sent Events (SSE). Enable real-time updates in the options to automatically update your UI when flag values change:

<FlagdeckProvider
  options={{
    apiKey: 'YOUR_API_KEY',
    realTimeUpdates: true,  // Enable real-time updates
  }}
  context={{
    userId: 'user-123',
    attributes: { plan: 'premium' }
  }}
>
  <YourApp />
</FlagdeckProvider>