Flipt Client Evaluation React SDK
npm install @flipt-io/flipt-client-react
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.
``bash`
npm install @flipt-io/flipt-client-react
- React 16.8.0 or higher
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.useFliptVariant
2. Use the hook for variant evaluation in a functional component that is wrapped in a FliptProvider.useFliptSelector
3. Use the 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.
First, wrap your application or a part of it with the FliptProvider:
`tsx
import { FliptProvider } from '@flipt-io/flipt-client-react';
function App() {
return (
environment: 'default',
namespace: 'default',
url: 'https://your-flipt-instance.com'
// Add other configuration options as needed
}}
>
{/ Your app components /}
);
}
`
#### 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).
`tsx
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 (
#### useFliptVariant Hook
The
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).`tsx
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 (
);
}
`$3
The
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`tsx
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 (
);
}
`$3
The
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.
- 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.$3
The
FliptProvider component supports the following authentication strategies:- No Authentication (default)
- Client Token Authentication
- JWT Authentication
Examples
Here's a more complete example of how to use the Flipt React SDK in your application:
`tsx
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 (
My App
{/ Will render the children if the feature flag evaluation results in true /}
This is a new feature!
);
}
export default App;
``Contributions are welcome! Please feel free to open an issue or submit a Pull Request.
This project is licensed under the MIT License.