> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lucenthq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# React API reference

> Provider, identify component, and hook exposed by @lucenthq/sdk/react.

The React entry point exposes three things: a **provider** that manages tracker
lifecycle, a **renderless identify component** that syncs user identity, and a
**hook** that returns the underlying tracker.

```ts theme={null}
import { LucentProvider, LucentIdentify, useLucent } from "@lucenthq/sdk/react";
```

## LucentProvider

Wraps your app, creates a single `LucentTracker` instance, and manages
`start`/`stop` across the component lifetime.

```tsx theme={null}
<LucentProvider publicKey="luc_pk_..." options={{ environment: "production" }}>
  {children}
</LucentProvider>
```

### Props

<ResponseField name="publicKey" type="string" required>
  Your Lucent publishable key (`luc_pk_...`). Safe to expose in client‑side
  code — it can only write session data to your org and cannot read anything.
</ResponseField>

<ResponseField name="options" type="Omit<LucentInitOptions, 'publicKey'>">
  Any option accepted by `LucentTracker` *except* `publicKey`. See the
  [Configuration](/sdk/configuration) page for the full list.
</ResponseField>

<ResponseField name="children" type="ReactNode" required>
  Your application tree.
</ResponseField>

### Lifecycle

The provider creates the tracker lazily on first render. On mount it calls
`tracker.start()` (unless `options.autoStart === false`). On unmount it calls
`tracker.stop()`, which flushes any buffered events.

<Warning>
  Do not remount `LucentProvider` on every render or route change — it should
  sit at the **root** of your app. Remounting will reset the recording session
  and cause gaps in your data.
</Warning>

## LucentIdentify

A renderless component that calls `tracker.identify(...)` whenever its props
change, and `tracker.resetIdentity()` when `userId` becomes null. Use it to
sync your auth state with Lucent declaratively.

```tsx theme={null}
<LucentProvider publicKey="luc_pk_...">
  <LucentIdentify
    userId={user?.id}
    email={user?.email}
    name={user?.name}
    properties={{
      plan: user?.plan,
      featureFlags: {
        "new-checkout-flow": flags.newCheckoutFlow,
      },
    }}
  />
  {children}
</LucentProvider>
```

### Props

<ResponseField name="userId" type="string | null">
  Your internal user ID. When this transitions from a value to `null`, Lucent
  resets the identity and generates a new anonymous ID.
</ResponseField>

<ResponseField name="email" type="string | null">
  Optional email address. Shown in the dashboard to help you find sessions.
</ResponseField>

<ResponseField name="name" type="string | null">
  Optional display name.
</ResponseField>

<ResponseField name="properties" type="Record<string, unknown>">
  Arbitrary key/value pairs attached to the user. Useful for plan tier,
  signup date, feature flags, etc.
</ResponseField>

### Feature flags for Signals

If your app records sessions with Lucent SDK and uses a separate feature flag
provider, pass the evaluated flag values through `properties.featureFlags`.
Signals can filter SDK sessions by these observed values.

```tsx theme={null}
<LucentIdentify
  userId={user?.id}
  email={user?.email}
  properties={{
    featureFlags: {
      "new-checkout-flow": launchDarkly.variation("new-checkout-flow"),
      "pricing-page-redesign": statsig.checkGate("pricing-page-redesign"),
      "paywall-test": growthbook.getFeatureValue("paywall-test", "control"),
    },
  }}
/>
```

Use the same flag key when creating a Signal filter. If a flag value changes
during the session, update the `properties` object so `LucentIdentify` calls
`identify` again.

## useLucent

Returns the tracker instance from the nearest `LucentProvider`, or `null` if
called outside a provider. Use this when you want to track custom events or
manually flush.

```tsx theme={null}
import { useLucent } from "@lucenthq/sdk/react";

export function CheckoutButton() {
  const lucent = useLucent();

  return (
    <button
      onClick={() => {
        lucent?.track("checkout_clicked", { plan: "pro" });
      }}
    >
      Upgrade
    </button>
  );
}
```

<Tip>
  `useLucent` returns `null` during SSR and on the first render if the provider
  hasn't mounted yet. Always guard with `lucent?.` or a conditional before
  calling methods.
</Tip>

For install steps, see [Next.js](/sdk/frameworks/nextjs) or [React](/sdk/frameworks/react).