schematic-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

``bash
npm install @schematichq/schematic-react


or

yarn add @schematichq/schematic-react

or

pnpm add @schematichq/schematic-react
`

Usage

$3

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(


,
document.getElementById("root"),
);
`

$3

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

;
};
`

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

$3

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

;
};
`

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 });
`

$3

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 ? : ;
};
`

$3

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 ;
}

// usage exceeded state
if (featureUsageExceeded) {
return (


);
}

// either feature state or "no access" state
return isFeatureEnabled ? : ;
};
`

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.

React Native

$3

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:

$3

Enables console logging of all Schematic operations:

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

ReactDOM.render(


,
document.getElementById("root"),
);

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

$3

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

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

ReactDOM.render(


,
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 and we'll be happy to assist.