Getting StartedFlagsSDKsWorkflowsAPI

React SDK

Client-side SDK for React web apps.

Overview

The React SDK exposes a singleton Flags client plus React hooks for subscribed reads.

Get started

Understand version compatibility

This package targets modern React apps and uses hook-based subscriptions.

Install the SDK

$Terminal
npm install react-featureflags-client

Initialize the client

TSTypeScript
import { useEffect } from "react";
import Flags from "react-featureflags-client";
export default function AppBootstrap() {
useEffect(() => {
void Flags.configure({
apiKey: process.env.NEXT_PUBLIC_TRUFLAG_CLIENT_KEY!,
user: {
id: "anon-session",
},
});
}, []);
return <AppRoutes />;
}

Login the context

TSTypeScript
import Flags from "react-featureflags-client";
await Flags.login({
id: "user-123",
attributes: {
plan: "enterprise",
country: "US",
},
});

Access flag values

Always pass a meaningful fallback. It is used before SDK state is ready and when the key is missing.

TSTypeScript
import Flags, { useFlag, useFlagsReady } from "react-featureflags-client";
export function CheckoutGate() {
const ready = useFlagsReady();
const enabled = useFlag("new-checkout-experience", false);
if (!ready) return <LoadingSkeleton />;
return enabled ? <CheckoutV2 /> : <CheckoutV1 />;
}
const checkoutVariant = Flags.getFlag("checkout-ui-variant", "control");

Optional: subscribe to SDK state changes

In normal React usage, hooks are already stateful and subscribe automatically. Use this only for advanced imperative integrations.

TSTypeScript
import { useEffect } from "react";
import Flags from "react-featureflags-client";
useEffect(() => {
return Flags.subscribe(() => {
// Optional imperative listener for non-hook integrations.
});
}, []);

Hooks

TTEXT
useFlagsReady(): boolean
useFlag<T>(flagKey: string, fallback: T): T
useFlagPayload(flagKey: string): Record<string, unknown> | null

Configuration options

TSTypeScript
Flags.configure({
apiKey: process.env.NEXT_PUBLIC_TRUFLAG_CLIENT_KEY!,
user: { id: "user-123", attributes: { plan: "pro" } },
streamEnabled: true,
pollingIntervalMs: 60_000,
cacheTtlMs: 300_000,
requestTimeoutMs: 6_000,
logLevel: "warn",
telemetryEnabled: true,
telemetryBatchSize: 50,
telemetryFlushIntervalMs: 10_000,
});

Full option details: SDK API reference.

Events

Flag reads emit exposures automatically. Use Flags.track() for custom events. Truflag automatically tracks Flag read events (i.e., getFlag or useFlag).

TSTypeScript
import Flags from "react-featureflags-client";
await Flags.track("checkout_completed", {
source: "web",
value: 1,
});

Flag keys in the React SDK

Use the exact flag key string from the dashboard in runtime reads and hooks.

Importing types

TSTypeScript
import type {
ConfigureOptions,
TrackOptions,
} from "react-featureflags-client";

Troubleshooting

Network error

Verify the public environment key, relay reachability, and request timeout settings.

CORS errors in local development

Confirm local app origin is allowed and the relay endpoint URL is correct for your environment.

Example app

TSTypeScript
import { useEffect } from "react";
import Flags, { useFlag, useFlagsReady } from "react-featureflags-client";
function Checkout() {
const ready = useFlagsReady();
const enabled = useFlag("new-checkout-experience", false);
if (!ready) return <p>Loading...</p>;
return <p>{enabled ? "New checkout" : "Legacy checkout"}</p>;
}
export default function App() {
useEffect(() => {
void Flags.configure({
apiKey: process.env.NEXT_PUBLIC_TRUFLAG_CLIENT_KEY!,
user: { id: "user-123", attributes: { plan: "pro" } },
});
}, []);
return <Checkout />;
}