FlagBox ReactJS documentation

The FlagBox React SDK provides a simple and powerful way to integrate feature flags into your React applications. Control your application's features in real-time with React hooks and context.

Installation

npm install @flagbox/react

Quick Start

import { FlagBoxProvider, useFeatureFlag } from 'flagbox';

// Wrap your app with the provider
function App() {
  const getConfig = async () => ({
    apiUrl: 'https://api.flagbox.io',
    apiKey: 'your-api-key',
    initialContext: {
      userId: 'user-123'
    }
  });

  return (
    <FlagBoxProvider getConfig={getConfig}>
      <YourApp />
    </FlagBoxProvider>
  );
}

// Use feature flags in your components
function FeatureComponent() {
  const isEnabled = useFeatureFlag('my-feature', false);

  return isEnabled ? (
    <div>New feature is active!</div>
  ) : (
    <div>Using old version</div>
  );
}

Configuration

The FlagBox provider can be configured with the following options:

getConfig (required): Async function that returns the configuration object
deferRendering (optional): Whether to wait for initialization before rendering children
loadingComponent (optional): Component to show while initializing

API Reference

FlagBoxProvider

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

interface FlagBoxConfig {
  apiUrl: string;
  apiKey: string;
  initialContext?: Record<string, any>;
}

interface FlagBoxProviderProps {
  getConfig: () => Promise<FlagBoxConfig>;
  children: ReactNode;
  deferRendering?: boolean;
  loadingComponent?: ReactNode;
}

useFeatureFlag

A React hook that returns the value of a feature flag.

// Basic usage
const isEnabled = useFeatureFlag('my-feature', false);

// With context
const isEnabled = useFeatureFlag('my-feature', false, {
  userId: 'user-123',
  plan: 'premium'
});

Error Handling

The SDK handles errors gracefully by:

Returning the default value when a flag cannot be fetched
Logging errors to the console for debugging
Providing error state through the context

Best Practices

Place the FlagBoxProvider at the root of your application
Use meaningful flag keys that describe the feature's purpose
Always provide a default value when using useFeatureFlag
Use initialContext for context values that are common across all flag evaluations
Keep context values under 256 characters to ensure they are included in the request
Use deferRendering when you need to ensure flags are loaded before rendering

Framework Integration

The SDK can be easily integrated with popular React frameworks:

// Next.js integration
import { FlagBoxProvider } from 'flagbox';

export default function App({ Component, pageProps }) {
  const getConfig = async () => ({
    apiUrl: process.env.NEXT_PUBLIC_FLAGBOX_API_URL,
    apiKey: process.env.NEXT_PUBLIC_FLAGBOX_API_KEY,
    initialContext: {
      environment: process.env.NODE_ENV
    }
  });

  return (
    <FlagBoxProvider getConfig={getConfig}>
      <Component {...pageProps} />
    </FlagBoxProvider>
  );
}

// Create React App integration
import { FlagBoxProvider } from 'flagbox';

function App() {
  const getConfig = async () => ({
    apiUrl: process.env.REACT_APP_FLAGBOX_API_URL,
    apiKey: process.env.REACT_APP_FLAGBOX_API_KEY,
    initialContext: {
      environment: process.env.NODE_ENV
    }
  });

  return (
    <FlagBoxProvider getConfig={getConfig}>
      <YourApp />
    </FlagBoxProvider>
  );
}