React
Read flags in React components with @toggld/react, a provider and hooks over the browser SDK.
@toggld/react connects the browser SDK to React. It works with React 18 and 19, and it supports server-side rendering.
Install
npm install @toggld/react @toggld/browser@toggld/browser is a peer dependency: you create the client with it.
Add the provider
Create one client for the page, outside your components. Then wrap your app in ToggldProvider:
import { ToggldClient } from "@toggld/browser";
import { ToggldProvider } from "@toggld/react";
const flags = new ToggldClient({
publicToken: "ffp_YOUR_PUBLIC_TOKEN",
context: { targetingKey: getVisitorId() },
});
export function App() {
return (
<ToggldProvider client={flags}>
<Checkout />
</ToggldProvider>
);
}Find the public token in Settings → API Keys. See Browser.
Read a flag
import { useFlag } from "@toggld/react";
function Checkout() {
const newCheckout = useFlag("new-checkout", false);
return newCheckout ? <NewCheckout /> : <OldCheckout />;
}The fallback value sets the flag type: false reads a boolean flag, "" a string flag, 0 a number flag, and an object or array an object flag. Until the values arrive, or if the flag cannot be evaluated, useFlag returns the fallback value.
A component re-renders only when the result of its flag changes. Changes to other flags do not re-render it.
Hooks
| Hook | Returns |
|---|---|
useFlag(key, fallback) | The flag's value. |
useFlagDetails(key, fallback) | The value with variant, reason, errorCode, errorMessage, and flagMetadata. |
useToggldStatus() | The client status: loading, ready, reconciling, or error. |
useToggldSnapshot() | The client's full state. It re-renders on every change. |
useToggldClient() | The client, for example to call setContext. |
Show a loading state
import { useToggldStatus } from "@toggld/react";
function Page() {
const status = useToggldStatus();
if (status === "loading") return <Spinner />;
return <Content />;
}Change the context
After sign-in, set the new context on the client. Components re-render when the new values arrive.
import { useToggldClient } from "@toggld/react";
function useSignIn() {
const flags = useToggldClient();
return async (user: User) => {
await flags.setContext({ targetingKey: user.id, plan: user.plan });
};
}Server-side rendering
Evaluate the flags on the server with @toggld/node and send the results to the page. Create the client in the root component with these results as bootstrap. Use useState, so that each server request gets its own client and the browser creates one client.
import { useState } from "react";
import { ToggldClient } from "@toggld/browser";
import { ToggldProvider } from "@toggld/react";
export function Root({ flagResults, context, children }) {
const [flags] = useState(
() => new ToggldClient({ publicToken: PUBLIC_TOKEN, context, bootstrap: flagResults }),
);
return <ToggldProvider client={flags}>{children}</ToggldProvider>;
}The server renders the correct variants, hydration matches, and the browser sends no first request. On the server, the client does not refresh.