Developer ResourcesSDKs

React

schematic-react is a client-side React library for Schematic which provides hooks to track events, check flags, and more. schematic-react provides the same capabilities as schematic-js, for React apps.

Install

$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:

1import { SchematicProvider } from "@schematichq/schematic-react";
2
3ReactDOM.render(
4    <SchematicProvider publishableKey="your-publishable-key">
5        <App />
6    </SchematicProvider>,
7    document.getElementById("root"),
8);

Setting context

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

1import { useSchematicEvents } from "@schematichq/schematic-react";
2
3const MyComponent = () => {
4    const { identify } = useSchematicEvents();
5
6    useEffect(() => {
7        identify({
8            keys: { id: "my-user-id" },
9            company: {
10                keys: { id: "my-company-id" },
11                traits: { location: "Atlanta, GA" },
12            },
13        });
14    }, []);
15
16    return <div>My Component</div>;
17};

To learn more about identifying companies with the keys map, see key management in Schematic public docs.

Tracking usage

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

1import { useSchematicEvents } from "@schematichq/schematic-react";
2
3const MyComponent = () => {
4    const { track } = useSchematicEvents();
5
6    useEffect(() => {
7        track({ event: "query" });
8    }, []);
9
10    return <div>My Component</div>;
11};

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:

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

Checking flags

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

1import { useSchematicFlag } from "@schematichq/schematic-react";
2import { Feature, Fallback } from "./components";
3
4const MyComponent = () => {
5    const isFeatureEnabled = useSchematicFlag("my-flag-key");
6
7    return isFeatureEnabled ? <Feature /> : <Fallback />;
8};

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:

1import {
2    useSchematicEntitlement,
3    useSchematicIsPending,
4} from "@schematichq/schematic-react";
5import { Feature, Loader, NoAccess } from "./components";
6
7const MyComponent = () => {
8    const schematicIsPending = useSchematicIsPending();
9    const {
10        featureAllocation,
11        featureUsage,
12        featureUsageExceeded,
13        value: isFeatureEnabled,
14    } = useSchematicEntitlement("my-flag-key");
15
16    // loading state
17    if (schematicIsPending) {
18        return <Loader />;
19    }
20
21    // usage exceeded state
22    if (featureUsageExceeded) {
23        return (
24            <div>
25                You have used all of your usage ({featureUsage} /{" "}
26                {featureAllocation})
27            </div>
28        );
29    }
30
31    // either feature state or "no access" state
32    return isFeatureEnabled ? <Feature /> : <NoAccess />;
33};

Troubleshooting

For debugging and development, Schematic supports two special modes:

Debug Mode

Enables console logging of all Schematic operations:

1// Enable at initialization
2import { SchematicProvider } from "@schematichq/schematic-react";
3
4ReactDOM.render(
5    <SchematicProvider publishableKey="your-publishable-key" debug={true}>
6        <App />
7    </SchematicProvider>,
8    document.getElementById("root"),
9);
10
11// Or via URL parameter
12// https://yoursite.com/?schematic_debug=true

Offline Mode

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

1// Enable at initialization
2import { SchematicProvider } from "@schematichq/schematic-react";
3
4ReactDOM.render(
5    <SchematicProvider publishableKey="your-publishable-key" offline={true}>
6        <App />
7    </SchematicProvider>,
8    document.getElementById("root"),
9);
10
11// Or via URL parameter
12// 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 and we’ll be happy to assist.

Next.js

If you’re building with Next.js, we recommend reading our Next.js SDK guide for more detailed recommendations on how implement Schematic in your Next.js application.