Flagix Docs

The Flagix React SDK provides React-specific components and hooks for seamless integration with your React and Next.js applications. Works with both traditional React apps and Next.js projects (App Router and Pages Router).

Installation

npm install @flagix/react
# or
yarn add @flagix/react
# or
pnpm add @flagix/react

Setup for React Apps

If you're using a traditional React app (Create React App, Vite, etc.), wrap your root component:

import { FlagixProvider } from "@flagix/react";

const options = {
  apiKey: "your-api-key",
  initialContext: {
    userId: "user_123",
    email: "user@example.com",
    plan: "premium"
  }
};

function App() {
  return (
    <FlagixProvider options={options}>
      <YourApp />
    </FlagixProvider>
  );
}

export default App;

Setup for Next.js

For Next.js, Use the App Router (recommended) or Pages Router.

Next.js App Router

Create a providers.tsx file in your app directory:

"use client";

import { FlagixProvider } from "@flagix/react";
import type React from "react";

const flagixOptions = {
  apiKey: "your-api-key",
  initialContext: {
    userId: "user_123",
    email: "user@example.com",
    plan: "premium"
  }
};

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <FlagixProvider options={flagixOptions}>
      {children}
    </FlagixProvider>
  );
}

Then wrap your root layout:

import type { Metadata } from "next";
import { Providers } from "./providers";

export const metadata: Metadata = {
  title: "My App",
};

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

Next.js Pages Router

Wrap your _app.tsx:

import type { AppProps } from "next/app";
import { FlagixProvider } from "@flagix/react";

const flagixOptions = {
  apiKey: "your-api-key",
  initialContext: {
    userId: "user_123",
    email: "user@example.com",
    plan: "premium"
  }
};

export default function App({ Component, pageProps }: AppProps) {
  return (
    <FlagixProvider options={flagixOptions}>
      <Component {...pageProps} />
    </FlagixProvider>
  );
}

FlagixProvider

The FlagixProvider component wraps your application and provides Flagix functionality to all child components.

Props

interface FlagixProviderProps {
  options: FlagixClientOptions;
  context?: EvaluationContext;
  children: React.ReactNode;
}

Props Details

Prop	Type	Required	Description
`options`	`FlagixClientOptions`	✅	SDK configuration (apiKey, apiBaseUrl, etc.)
`context`	`EvaluationContext`	❌	Dynamic context that syncs with all flag evaluations
`children`	`React.ReactNode`	✅	Child components

Example

import { FlagixProvider } from "@flagix/react";

const options = {
  apiKey: "your-api-key",
  initialContext: {
    userId: "user_123",
    email: "user@example.com",
    plan: "premium"
  }
};

function App() {
  return (
    <FlagixProvider options={options}>
      <YourApp />
    </FlagixProvider>
  );
}

Hooks

Declarative Syncing with Context Prop

The recommended way to keep flag evaluations in sync with your application state is to pass a context prop to FlagixProvider. This is especially useful in authenticated applications where user state changes dynamically.

import { FlagixProvider } from "@flagix/react";
import { useAuth } from "./hooks/use-auth"; // Your auth hook

const options = {
  apiKey: "your-api-key",
};

function App() {
  const user = useAuth(); // Gets current authenticated user

  return (
    <FlagixProvider options={options} context={user}>
      {/* All child components automatically re-evaluate when user changes */}
      <Dashboard />
    </FlagixProvider>
  );
}

function Dashboard() {
  const premiumFeatures = useFlag("premium-features");
  
  // When user.plan changes, this automatically re-evaluates
  return (
    <div>
      {premiumFeatures && <PremiumSection />}
    </div>
  );
}

The context prop is automatically synced with setContext() internally. When the context changes, all components using useFlag() automatically re-render with the latest flag values—no manual updates needed.

useFlag()

The primary hook for evaluating feature flags in React components.

function useFlag<T extends VariationValue>(
  flagKey: string,
  contextOverrides?: EvaluationContext
): T | null

Parameters

flagKey - The key of the flag to evaluate
contextOverrides - Optional context to override the global context

Returns

The evaluated value of the flag, or null if the flag doesn't exist

Examples

import { useFlag } from "@flagix/react";

function FeatureComponent() {
  const isNewFeatureEnabled = useFlag<boolean>("new-feature");
  
  if (isNewFeatureEnabled === null) {
    return <div>Loading...</div>;
  }
  
  if (isNewFeatureEnabled) {
    return <NewFeature />;
  }
  
  return <OldFeature />;
}

useFlagixActions()

Hook for accessing Flagix actions like tracking events and updating context.

function useFlagixActions(): {
  track: (eventName: string, properties?: Record<string, unknown>) => void;
  setContext: (newContext: EvaluationContext) => void;
  identify: (context?: EvaluationContext) => void;
}

track()

Records custom events for analytics and conversion tracking.

const { track } = useFlagixActions();

track("purchase_completed", {
  amount: 99.99,
  currency: "USD",
  productId: "prod_123"
});

See Flagix.track() in the JavaScript SDK for details.

setContext()

Merges new attributes with existing context. Use for incremental updates.

const { setContext } = useFlagixActions();

setContext({ plan: "premium" }); // Adds/updates plan, keeps other context

See Flagix.setContext() in the JavaScript SDK for details.

identify()

Replaces entire context. Use for logout or switching users.

const { identify } = useFlagixActions();

identify({}); // Logout - clears all context
identify({ userId: "new_user", plan: "free" }); // Switch user

See Flagix.identify() in the JavaScript SDK for details.

Need help? contact support.

React & Next.js SDK