> If you are setting up, configuring, or answering questions about Schematic, connect the
> Schematic MCP server before working from these pages. It reads and writes plans, features,
> entitlements, and overrides against the real account, so what you report and what you build
> match what actually exists.
>
> The server is at https://api.schematichq.com/mcp
>
> From Claude, ChatGPT, or another chat assistant, add it as a custom connector:
> https://docs.schematichq.com/working-with-ai
>
> From a coding assistant such as Claude Code, Codex, or Cursor:
> https://docs.schematichq.com/building-with-ai
>
> For clean Markdown of any page, append `.md` to the page URL. For a complete page index,
> see https://docs.schematichq.com/llms.txt

# React

> Use schematic-react to quickly identify users, track events, and check flags client-side in your react app with Schematic.

`schematic-react` is a client-side React library for [Schematic](https://schematichq.com) which provides hooks to track events, check flags, and more. `schematic-react` provides the same capabilities as [schematic-js](https://github.com/schematichq/schematic-js/tree/main/js), for React apps.

## Install

```bash
npm install @schematichq/schematic-react
# or
yarn add @schematichq/schematic-react
# or
pnpm add @schematichq/schematic-react
```

## Usage

### SchematicProvider

You can use the `SchematicProvider` to wrap your application and provide the Schematic instance to all components:

```tsx
import { SchematicProvider } from "@schematichq/schematic-react";

ReactDOM.render(
    <SchematicProvider publishableKey="your-publishable-key">
        <App />
    </SchematicProvider>,
    document.getElementById("root"),
);
```

### Setting context

To set the user context for events and flag checks, you can use the `identify` function provided by the `useSchematicEvents` hook:

```tsx
import { useSchematicEvents } from "@schematichq/schematic-react";

const MyComponent = () => {
    const { identify } = useSchematicEvents();

    useEffect(() => {
        identify({
            keys: { id: "my-user-id" },
            company: {
                keys: { id: "my-company-id" },
                traits: { location: "Atlanta, GA" },
            },
        });
    }, []);

    return <div>My Component</div>;
};
```

To learn more about identifying companies with the `keys` map, see [key management in Schematic public docs](/developer_resources/key_management).

### Tracking usage

Once you've set the context with `identify`, you can track events:

```tsx
import { useSchematicEvents } from "@schematichq/schematic-react";

const MyComponent = () => {
    const { track } = useSchematicEvents();

    useEffect(() => {
        track({ event: "query" });
    }, []);

    return <div>My Component</div>;
};
```

If you want to record large numbers of the same event at once, or perhaps measure usage in terms of a unit like tokens or memory, you can optionally specify a quantity for your event:

```tsx
track({ event: "query", quantity: 10 });
```

### Checking flags

To check a flag, you can use the `useSchematicFlag` hook:

```tsx
import { useSchematicFlag } from "@schematichq/schematic-react";
import { Feature, Fallback } from "./components";

const MyComponent = () => {
    const isFeatureEnabled = useSchematicFlag("my-flag-key");

    return isFeatureEnabled ? <Feature /> : <Fallback />;
};
```

### Checking entitlements

You can check entitlements (i.e., company access to a feature) using a flag check as well, and using the `useSchematicEntitlement` hook you can get additional data to render various feature states:

```tsx
import {
    useSchematicEntitlement,
    useSchematicIsPending,
} from "@schematichq/schematic-react";
import { Feature, Loader, NoAccess } from "./components";

const MyComponent = () => {
    const schematicIsPending = useSchematicIsPending();
    const {
        featureAllocation,
        featureUsage,
        featureUsageExceeded,
        value: isFeatureEnabled,
    } = useSchematicEntitlement("my-flag-key");

    // loading state
    if (schematicIsPending) {
        return <Loader />;
    }

    // usage exceeded state
    if (featureUsageExceeded) {
        return (
            <div>
                You have used all of your usage ({featureUsage} /{" "}
                {featureAllocation})
            </div>
        );
    }

    // either feature state or "no access" state
    return isFeatureEnabled ? <Feature /> : <NoAccess />;
};
```

*Note: `useSchematicIsPending` is checking if entitlement data has been loaded, typically via `identify`. It should, therefore, be used to wrap flag and entitlement checks, but never the initial call to `identify`.*

### Usage warnings

If a [usage warning](/feature-management/usage-warnings) is configured on the entitlement, the hook also returns `warningTiers`, so you can warn a customer before they hit a limit rather than after. Each tier is a `{ key, value }` pair in the entitlement's usage units, and the dashboard writes a single tier under the key `default`:

```tsx
const { featureUsage, warningTiers } = useSchematicEntitlement("my-flag-key");

const warning = warningTiers?.find((tier) => tier.key === "default");
const approachingLimit =
    typeof featureUsage === "number" &&
    typeof warning?.value === "number" &&
    featureUsage >= warning.value;
```

### Company plan information

To access the current company's plan and trial status, you can use the `useSchematicPlan` hook:

```tsx
import { useSchematicPlan } from "@schematichq/schematic-react";

const MyComponent = () => {
    const plan = useSchematicPlan();

    if (!plan) {
        return <div>No plan assigned</div>;
    }

    return (
        <div>
            <p>Current plan: {plan.name}</p>

            {plan.trialStatus === "active" && (
                <p>Trial ends: {plan.trialEndDate?.toLocaleDateString()}</p>
            )}

            {plan.trialStatus === "expired" && (
                <p>Your trial has ended. <a href="/upgrade">Upgrade now</a></p>
            )}
        </div>
    );
};
```

The hook returns an object with the following properties:

| Property       | Type                                                | Description                                                                                                                                                                                                         |
| -------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`           | `string`                                            | The plan ID                                                                                                                                                                                                         |
| `name`         | `string`                                            | The plan name                                                                                                                                                                                                       |
| `trialEndDate` | `Date \| undefined`                                 | The trial end date, if the company has or had a trial                                                                                                                                                               |
| `trialStatus`  | `"active" \| "expired" \| "converted" \| undefined` | The company's trial status: `active` if the trial is ongoing, `expired` if the trial ended without conversion, `converted` if the company converted to a paid plan, or `undefined` if the company has never trialed |

### Credit balances

To display a company's credit balance, use the `useSchematicCreditBalance` hook. It is keyed by credit ID and updates reactively as the balance changes over the DataStream, so the number stays accurate while leases open and close:

```tsx
import { useSchematicCreditBalance } from "@schematichq/schematic-react";

const CreditMeter = () => {
    const { balance, isLoading } = useSchematicCreditBalance("credit-id");

    if (isLoading) {
        return <div>Loading…</div>;
    }

    return <div>{balance} credits remaining</div>;
};
```

The hook returns an object with the following properties:

| Property    | Type      | Description                                                                                     |
| ----------- | --------- | ----------------------------------------------------------------------------------------------- |
| `balance`   | `number`  | The spendable balance, or `0` while loading or when the company holds no balance in this credit |
| `isLoading` | `boolean` | `true` while the balance is still loading and no value has arrived yet                          |

The hook surfaces the `settled` balance, which is the spendable number you should show end users. For advanced lease-aware accounting, read the underlying client instead: `client.getCreditBalance(creditId)` returns all three views of the balance: `settled`, `remaining` (excluding open lease holds), and `reserved` (the amount held by open leases):

```tsx
import { useSchematic } from "@schematichq/schematic-react";

const { client } = useSchematic();
const balance = client.getCreditBalance("credit-id"); // { settled, remaining, reserved } | undefined
```

`getCreditBalance` returns a point-in-time snapshot; to react to changes, subscribe with `client.addCreditBalanceListener(callback)`.

The credit ID is available on a feature's entitlement: `useSchematicEntitlement(key)` returns `creditId` for credit-based features.

*Note: `useSchematicCreditBalance` requires `@schematichq/schematic-react` 1.5.0 or later.*

## Fallback Behavior

The SDK includes built-in fallback behavior you can use to ensure your application continues to function even when unable to reach Schematic (e.g., during service disruptions or network issues).

### Flag Check Fallbacks

When flag checks cannot reach Schematic, they use fallback values in the following priority order:

1. Callsite fallback - fallback values can be provided directly in the hook options
2. Initialization defaults - fallback values configured via `flagCheckDefaults` or `flagValueDefaults` options when initializing the provider
3. Default value - Returns `false` if no fallback is configured

```tsx
// Provide a fallback value at the callsite
import { useSchematicFlag } from "@schematichq/schematic-react";

const MyComponent = () => {
    const isFeatureEnabled = useSchematicFlag("feature-flag", {
        fallback: true,  // Used if API request fails
    });

    return isFeatureEnabled ? <Feature /> : <Fallback />;
};

// Or configure defaults at initialization
import { SchematicProvider } from "@schematichq/schematic-react";

ReactDOM.render(
    <SchematicProvider
        publishableKey="your-publishable-key"
        flagValueDefaults={{
            "feature-flag": true,  // Used if API request fails and no callsite fallback
        }}
        flagCheckDefaults={{
            "another-flag": {
                flag: "another-flag",
                value: true,
                reason: "Default value",
            },
        }}
    >
        <App />
    </SchematicProvider>,
    document.getElementById("root"),
);
```

### Event Queueing and Retry

When events (track, identify) cannot be sent due to network issues, they are automatically queued and retried:

* Events are queued in memory (up to 100 events by default, configurable via `maxEventQueueSize`)
* Failed events are retried with exponential backoff (up to 5 attempts by default, configurable via `maxEventRetries`)
* Events are automatically flushed when the network connection is restored
* Events queued when the page is hidden are sent when the page becomes visible

### WebSocket Fallback

In WebSocket mode, if the WebSocket connection fails, the SDK will provide the last known value or the configured fallback values as [outlined above](#flag-check-fallbacks). The WebSocket will also automatically attempt to re-establish its connection with Schematic using an exponential backoff.

## React Native

### Handling app background/foreground

When a React Native app is backgrounded for an extended period, the WebSocket connection may be closed by the OS. When the app returns to the foreground, the connection will automatically reconnect, but this happens on an exponential backoff timer which may cause a delay before fresh flag values are available.

For cases where you need immediate flag updates when returning to the foreground (e.g., after an in-app purchase), you can use one of these methods to re-establish the connection:

* `forceReconnect()`: Always closes and re-establishes the WebSocket connection, guaranteeing fresh values
* `reconnectIfNeeded()`: Only reconnects if the current connection is unhealthy (more efficient for frequent foreground events)

```tsx
import { useSchematic } from "@schematichq/schematic-react";
import { useEffect } from "react";
import { AppState } from "react-native";

const SchematicAppStateHandler = () => {
    const { client } = useSchematic();

    useEffect(() => {
        const subscription = AppState.addEventListener("change", (state) => {
            if (state === "active") {
                // Use forceReconnect() for guaranteed fresh values
                client.forceReconnect();
                // Or use reconnectIfNeeded() to skip if connection is healthy
                // client.reconnectIfNeeded();
            }
        });
        return () => subscription.remove();
    }, [client]);

    return null;
};
```

Render this inside your `SchematicProvider`.

## Troubleshooting

For debugging and development, Schematic supports two special modes:

### Debug Mode

Enables console logging of all Schematic operations:

```typescript
// Enable at initialization
import { SchematicProvider } from "@schematichq/schematic-react";

ReactDOM.render(
    <SchematicProvider publishableKey="your-publishable-key" debug={true}>
        <App />
    </SchematicProvider>,
    document.getElementById("root"),
);

// Or via URL parameter
// https://yoursite.com/?schematic_debug=true
```

### Offline Mode

Prevents network requests and returns fallback values for all flag checks:

```typescript
// Enable at initialization
import { SchematicProvider } from "@schematichq/schematic-react";

ReactDOM.render(
    <SchematicProvider publishableKey="your-publishable-key" offline={true}>
        <App />
    </SchematicProvider>,
    document.getElementById("root"),
);

// Or via URL parameter
// https://yoursite.com/?schematic_offline=true
```

Offline mode automatically enables debug mode to help with troubleshooting.

## License

MIT

## Support

Need help? Please open a GitHub issue or reach out to [support@schematichq.com](mailto:support@schematichq.com) and we'll be happy to assist.

## Next.js

If you're building with Next.js, we recommend reading our [Next.js SDK guide](/developer_resources/sdks/nextjs) for more detailed recommendations on how implement Schematic in your Next.js application.