React SDK

The @tracio/react package wraps the core @tracio/sdk and exposes idiomatic React primitives: a provider that mounts the agent, and hooks that hand you the visitor ID and identification result with loading and error state.

Installation

npm install @tracio/react @tracio/sdk

react (18 or 19) is a peer dependency and is expected to already be installed in your app.

Setup

Wrap your application with <TracioProvider>. It mounts the TRACIO agent on first render and calls tracio.destroy() automatically when the provider unmounts.

import { TracioProvider } from "@tracio/react"

function Root() {
  return (
    <TracioProvider publicKey={process.env.NEXT_PUBLIC_TRACIO_KEY!}>
      <App />
    </TracioProvider>
  )
}

Provider props

Pass either publicKey plus the flat scalars, or a complete config object. When both are supplied, config wins.

Hooks

useVisitorId()

Returns the stable visitor identifier with loading and error state.

const { data, isLoading, error, isFetched, getId } = useVisitorId()
// data: string | undefined — the visitorId

getId() re-fetches the visitor ID imperatively.

useTracioResult(opts?)

Returns the full TracioResult (visitor ID plus bot detection).

const { data, isLoading, error, isFetched, getData } = useTracioResult()
// data: TracioResult | undefined

opts.immediate defaults to true. Pass { immediate: false } to defer the fetch until you call getData() yourself — useful behind a consent gate:

const { data, getData } = useTracioResult({ immediate: false })

function onConsent() {
  getData() // identify only after the user opts in
}

useTracio()

Escape hatch that returns the underlying instance for advanced use.

const { tracio } = useTracio()

Full example

import { TracioProvider, useVisitorId } from "@tracio/react"
function App() {
  return (
    <TracioProvider publicKey={process.env.NEXT_PUBLIC_TRACIO_KEY!}>
      <Page />
    </TracioProvider>
  )
}
function Page() {
  const { data: visitorId, isLoading, error } = useVisitorId()
  if (isLoading) return <span>Loading…</span>
  if (error) return <span>Error: {error.message}</span>
  return <span>Visitor: {visitorId}</span>
}

Next steps

• JavaScript SDK Reference — the core @tracio/sdk API the hooks build on
• Error Handling — error codes and retry strategies
• SDKs overview — every framework package at a glance