Flipt React SDK

The Flipt React SDK provides a convenient way to integrate Flipt feature flags into your React applications using a custom hook and a context provider. It is built on top of the Flipt client-side evaluation client for the browser.

Installation

npm install @flipt-io/flipt-client-react

Prerequisites

• React 16.8.0 or higher

Usage

There are three ways to use the Flipt React SDK.

1. Use the useFliptBoolean hook for boolean evaluation in a functional component that is wrapped in a FliptProvider.
2. Use the useFliptVariant hook for variant evaluation in a functional component that is wrapped in a FliptProvider.
3. Use the useFliptSelector hook for custom evaluation in a functional component that is wrapped in a FliptProvider.

[!TIP] Looking for NextJS support? Check out our NextJS examples in the main Flipt repo.

FliptProvider

First, wrap your application or a part of it with the FliptProvider:

import { FliptProvider } from '@flipt-io/flipt-client-react';

function App() {
  return (
    <FliptProvider
      options={{
        environment: 'default',
        namespace: 'default',
        url: 'https://your-flipt-instance.com'
        // Add other configuration options as needed
      }}
    >
      {/* Your app components */}
    </FliptProvider>
  );
}

useFliptBoolean Hook

The useFliptBoolean hook simplifies the process of evaluating a boolean feature flag. This hook must be used within a functional component that is wrapped by the FliptProvider context. A default value is returned if the feature flag cannot be evaluated at the current time (e.g., due to network issues or missing data).

import { useFliptBoolean } from '@flipt-io/flipt-client-react';

function MyComponent() {
  const result = useFliptBoolean('my-flag', false, 'user-123', {
    // additional context
  });
  const handleCheckFlag = async () => {
    console.log('Flag evaluation result:', result);
  };

  return (
    <div>
      <button onClick={handleCheckFlag}>Check Flag</button>
    </div>
  );
}

useFliptVariant Hook

The useFliptVariant hook simplifies the process of evaluating a variant feature flag. This hook must be used within a functional component that is wrapped by the FliptProvider context. A default value is returned if the feature flag cannot be evaluated at the current time (e.g., due to network issues or missing data).

import { useFliptVariant } from '@flipt-io/flipt-client-react';

function MyComponent() {
  const result = useFliptVariant('my-flag', 'fallback', 'user-123', {
    // additional context
  });
  const handleCheckFlag = async () => {
    console.log('Flag evaluation result:', result);
  };

  return (
    <div>
      <button onClick={handleCheckFlag}>Check Flag</button>
    </div>
  );
}

useFliptSelector Hook

The useFliptSelector hook allows direct access to the Flipt client so that it can be used in a functional component that is wrapped in a FliptProvider.

This is useful for more complex evaluations or in cases where you wish to call other methods on the Flipt client.

[!WARNING] flipt-client-react heavily depends on the useSyncExternalStore hook which has some caveats

import { useFliptSelector } from '@flipt-io/flipt-client-react';

function MyComponent() {
  const result = useFliptSelector((client, isLoading, error) => {
    const result = client?.evaluateBoolean('my-flag', 'user-123', {
      // additional context
    });
    console.log('Flag evaluation internals:', result, isLoading, error);
    return result?.enabled;
  });

  // Use the client to evaluate flags
  const handleCheckFlag = async () => {
    console.log('Flag evaluation result:', result);
  };

  return (
    <div>
      <button onClick={handleCheckFlag}>Check Flag</button>
    </div>
  );
}

Initialization Arguments

The FliptProvider component accepts two optional arguments:

• options: An instance of the ClientOptions type that supports several options for the client. The structure is:
  • environment: The environment to use when evaluating flags (Flipt v2). If not provided, the client will default to the default environment.
  • namespace: The namespace to fetch flag state from. If not provided, the client will default to the default namespace.
  • url: The URL of the upstream Flipt instance. If not provided, the client will default to http://localhost:8080.
  • authentication: The authentication strategy to use when communicating with the upstream Flipt instance. If not provided, the client will default to no authentication. See the Authentication section for more information.
  • updateInterval: The polling interval (in seconds) for fetching new state from Flipt. Set to 120 seconds by default. A 0 value disables polling completely after the initial fetch.
  • reference: The reference to use when fetching flag state. If not provided, reference will not be used.
  • snapshot: A base64-encoded snapshot returned by the underlying JS client's getSnapshot() method. Use this with errorStrategy: ErrorStrategy.Fallback to allow startup while Flipt is unreachable.
  • errorStrategy: The strategy for fetch errors. Use ErrorStrategy.Fallback with snapshot for offline startup.
  • fetchMode: FetchMode.Polling (default) or FetchMode.Streaming. With @flipt-io/flipt-client-js 0.7.0 or later, components re-render whenever the client applies changed flag state, including streamed updates.
  • fetcher: An implementation of a fetcher interface to use when requesting flag state. If not provided, a default fetcher using the browser's fetch API will be used.

Authentication

The FliptProvider component supports the following authentication strategies:

• No Authentication (default)
• Client Token Authentication
• JWT Authentication

Offline Startup with Snapshots

flipt-client-react uses @flipt-io/flipt-client-js under the hood, so it supports the same manual snapshot flow. Store the snapshot yourself, then pass it through FliptProvider options on the next page load.

import { ErrorStrategy } from '@flipt-io/flipt-client-js';
import { FliptProvider, useFliptSelector } from '@flipt-io/flipt-client-react';

function PersistFliptSnapshot() {
  useFliptSelector((client) => {
    if (client) {
      localStorage.setItem('fliptSnapshot', client.getSnapshot());
    }
    return null;
  });

  return null;
}

function App() {
  const snapshot = localStorage.getItem('fliptSnapshot') ?? undefined;

  return (
    <FliptProvider
      options={{
        namespace: 'default',
        url: 'https://your-flipt-instance.com',
        snapshot,
        errorStrategy: ErrorStrategy.Fallback
      }}
    >
      <PersistFliptSnapshot />
      {/* Your app components */}
    </FliptProvider>
  );
}

The provider will use the cached snapshot if startup fetch fails. When Flipt is reachable, fresh state replaces the cached snapshot and getSnapshot() returns the latest state.

Examples

Here's a more complete example of how to use the Flipt React SDK in your application:

import React from 'react';
import { FliptProvider, useFliptBoolean } from '@flipt-io/flipt-client-react';

// A custom component that renders its children if the feature flag is enabled
function FeatureFlag({ flagKey, entityId, children }) {
  const isEnabled = useFliptBoolean('flagKey', false, entityId, {
    // additional context
  });
  return isEnabled ? children : null;
}

function App() {
  return (
    <FliptProvider options={{ url: 'https://your-flipt-instance.com' }}>
      <h1>My App</h1>
      {/* Will render the children if the feature flag evaluation results in true */}
      <FeatureFlag flagKey="new-feature" entityId="user-123">
        <div>This is a new feature!</div>
      </FeatureFlag>
    </FliptProvider>
  );
}

export default App;

Contributing

Contributions are welcome! Please feel free to open an issue or submit a Pull Request.

License

This project is licensed under the MIT License.