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.