React bindings for FlipFlag — feature flags and remote configuration for React and Next.js applications.
Built on top of @flipflag/sdk, this package provides idiomatic React APIs:
providers, hooks, and safe client-side defaults.
- React-first API (
Provider, hooks) - Works with React 18+ and Next.js (App & Pages Router)
- Safe by default for the browser (public key only)
- Automatic re-rendering on flag updates
- Optional SSR-friendly bootstrapping
- Full TypeScript support
- Zero config required on the client
npm install @flipflag/react @flipflag/sdk
# or
yarn add @flipflag/react @flipflag/sdk
reactand@flipflag/sdkare declared as peer dependencies.
-
FlipFlagProvider
Owns a singleFlipFlagmanager instance and handles lifecycle (init, polling,destroy). -
Hooks (
useFlag,useFlags)
Read feature flags reactively inside components. -
Client-safe by default
Designed to run in the browser using a public key only.
import { FlipFlagProvider, useFlag } from "@flipflag/react";
function NewNavbar() {
const enabled = useFlag("new-navbar", false);
return enabled ? <div>New navbar</div> : <div>Old navbar</div>;
}
export function App() {
return (
<FlipFlagProvider
options={{
publicKey: "YOUR_PUBLIC_KEY",
}}
>
<NewNavbar />
</FlipFlagProvider>
);
}"use client";
import { FlipFlagProvider } from "@flipflag/react";
export function Providers({ children }: { children: React.ReactNode }) {
return (
<FlipFlagProvider
options={{
publicKey: process.env.NEXT_PUBLIC_FLIPFLAG_PUBLIC_KEY!,
ignoreMissingConfig: true
}}
>
{children}
</FlipFlagProvider>
);
}import { Providers } from "./providers";
export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
<html>
<body>
<Providers>{children}</Providers>
</body>
</html>
);
}Returns a boolean feature flag value.
const enabled = useFlag("checkout-v2");With fallback:
const enabled = useFlag("checkout-v2", false);Read multiple flags at once.
const flags = useFlags(["checkout-v2", "new-navbar"] as const);
flags["checkout-v2"];
flags["new-navbar"];Check SDK initialization state.
const { ready, error } = useFlipFlagReady();
if (!ready) return <Spinner />;
if (error) return <ErrorState />;export type FlipFlagReactOptions = {
publicKey: string;
privateKey?: string; // ⚠️ server-only
apiUrl?: string;
configPath?: string;
ignoreMissingConfig?: boolean;
refreshIntervalMs?: number; // default: 10_000
initialFlags?: Record<string, boolean>;
};MIT License