React

Installation

npm install --save @outlit/browser

pnpm add @outlit/browser

yarn add @outlit/browser

bun add @outlit/browser

Quick start

Wrap your app with OutlitProvider and use the useOutlit hook in components.

With authentication (recommended)
Anonymous only

If your app has user authentication, pass the user identity via the user prop. This is the recommended approach as it automatically handles login/logout transitions.

// app/providers.tsx (Client Component)
'use client'

import { OutlitProvider } from '@outlit/browser/react'
import { useUser } from '@clerk/nextjs' // or useAuth0, useSession, etc.

export function Providers({ children }: { children: React.ReactNode }) {
  const { user, isLoaded } = useUser()

  // Build user identity from your auth provider
  const outlitUser = isLoaded && user ? {
    email: user.primaryEmailAddress?.emailAddress,
    userId: user.id,
    traits: {
      name: user.fullName,
    }
  } : null

  return (
    <OutlitProvider 
      publicKey="pk_your_key" 
      trackPageviews
      user={outlitUser}
    >
      {children}
    </OutlitProvider>
  )
}

// app/layout.tsx
import { Providers } from './providers'

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  )
}

For marketing sites without authentication, add the provider via a client component:

// app/providers.tsx (Next.js App Router)
'use client'

import { OutlitProvider } from '@outlit/browser/react'

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <OutlitProvider publicKey="pk_your_key" trackPageviews>
      {children}
    </OutlitProvider>
  )
}

// app/layout.tsx
import { Providers } from './providers'

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  )
}

Using the hook

Track custom events with the useOutlit hook:

// components/pricing-button.tsx
'use client'

import { useOutlit } from '@outlit/browser/react'

export function PricingButton() {
  const { track } = useOutlit()

  return (
    <button onClick={() => track('pricing_clicked', { plan: 'pro' })}>
      View Pricing
    </button>
  )
}

Provider configuration

OutlitProvider

The OutlitProvider initializes tracking and provides context to child components.

import { OutlitProvider } from '@outlit/browser/react'

<OutlitProvider
  publicKey="pk_xxx"
  trackPageviews={true}
  trackForms={true}
  trackEngagement={true}
  formFieldDenylist={['custom_secret_field']}
  flushInterval={5000}
>
  {children}
</OutlitProvider>

Props

string

required

Your organization’s public key.

string

default:"https://app.outlit.ai"

API endpoint for sending events.

boolean

default:"true"

Automatically track pageviews on route changes.

boolean

default:"true"

Automatically capture form submissions.

string[]

Additional field names to exclude from form capture.

number

default:"5000"

How often to flush queued events (ms).

boolean | "auto"

default:"\"auto\""

Controls when tracking starts. "auto" (default) asks the Outlit edge endpoint whether the visitor’s region requires opt-in consent: tracking enables automatically outside the EEA, UK, and Switzerland, and stays off in those regions or when the region can’t be determined. The check fails closed on errors. true enables immediately; false waits for enableTracking() from the useOutlit hook. isTrackingEnabled updates automatically when auto mode enables tracking asynchronously.

boolean

default:"true"

Automatically identify users when they submit forms containing an email field. Extracts email and name (first name, last name, full name) using field name heuristics. Set to false to disable and call identify() manually. See Auto-identify for details.

boolean

default:"true"

Track engagement metrics (active time on page). Emits engagement events on page exit and navigation.

number

default:"30000"

Idle timeout in milliseconds for engagement tracking. After this period of no user interaction, the user is considered idle.

boolean

default:"true"

Track booking events from calendar embeds (Cal.com, Calendly).

UserIdentity | null

Current user identity. When provided with email or userId, identifies the user. When null or undefined, clears the user identity. This is the recommended way to handle user identity in server-rendered apps.

Outlit

An existing Outlit instance to use instead of creating one internally. When provided, config props (publicKey, apiHost, etc.) are ignored and shutdown() is not called on unmount — the caller owns the instance lifecycle. Useful for sharing a single instance between imperative usage and React context.

Client mode

If you need to use the same Outlit instance both imperatively and via React context, pass an existing instance with the client prop:

import { Outlit } from '@outlit/browser'
import { OutlitProvider } from '@outlit/browser/react'

const outlit = new Outlit({ publicKey: 'pk_xxx' })

// Imperative usage outside React
outlit.track('app_loaded')

function App() {
  return (
    <OutlitProvider client={outlit}>
      {children}
    </OutlitProvider>
  )
}

When using client, the provider does not call shutdown() on unmount — you own the instance lifecycle. Config props like publicKey and trackPageviews are ignored.

User identity patterns

The user prop is the recommended way to handle user identity. It’s simpler and more reliable than manual identify() calls because:

Automatic lifecycle management: Login/logout transitions are handled automatically
No timing issues: Identity is set before any events are tracked
Cleaner code: No need for useEffect + identify() synchronization

Pattern 1: client-side auth (Clerk, Auth0, etc.)

For auth libraries that provide React hooks:

// app/providers.tsx
'use client'

import { OutlitProvider } from '@outlit/browser/react'
import { useUser } from '@clerk/nextjs' // or useAuth0, useSession, etc.

export function Providers({ children }: { children: React.ReactNode }) {
  const { user, isLoaded } = useUser()

  const outlitUser = isLoaded && user ? {
    email: user.primaryEmailAddress?.emailAddress,
    userId: user.id,
    traits: { name: user.fullName }
  } : null

  return (
    <OutlitProvider publicKey="pk_xxx" user={outlitUser}>
      {children}
    </OutlitProvider>
  )
}

Pattern 2: server-side auth (NextAuth, Lucia, etc.)

For auth systems where session is available server-side, read the session in the Server Component and pass the resolved user into a client wrapper — OutlitProvider itself must render inside a client component (the package does not ship a 'use client' entry).

// app/providers.tsx (Client Component)
'use client'

import { OutlitProvider } from '@outlit/browser/react'
import type { UserIdentity } from '@outlit/browser'

export function Providers({
  children,
  user,
}: {
  children: React.ReactNode
  user: UserIdentity | null
}) {
  return (
    <OutlitProvider publicKey={process.env.NEXT_PUBLIC_OUTLIT_KEY!} user={user}>
      {children}
    </OutlitProvider>
  )
}

// app/layout.tsx (Server Component)
import { Providers } from './providers'
import { auth } from '@/auth' // Your auth library

export default async function RootLayout({ children }) {
  const session = await auth()

  return (
    <html>
      <body>
        <Providers
          user={session?.user ? {
            email: session.user.email,
            userId: session.user.id,
            traits: { name: session.user.name }
          } : null}
        >
          {children}
        </Providers>
      </body>
    </html>
  )
}

Which pattern should I use?

Client-side auth hooks (Clerk, Auth0): Use Pattern 1 with a client providers component
Server-side sessions (NextAuth, Lucia, custom JWT): Use Pattern 2 — resolve the session in the server layout, pass user into a client Providers wrapper

Both patterns work equally well - choose based on how your auth library provides user data. In the App Router, OutlitProvider (and useOutlit) must always render inside a component with 'use client'. When the user prop changes (login/logout), the provider automatically calls setUser() or clearUser() internally. You don’t need to call these methods manually. The default autoTrack: "auto" mode already keeps tracking off for visitors in regions that require opt-in consent (EEA, UK, Switzerland, or unknown). enableTracking() — typically wired to your consent banner’s accept action — is what grants consent and is persisted for future sessions. To wait for enableTracking() instead — unless a previous opt-in is stored:

// app/layout.tsx
import { OutlitProvider } from '@outlit/browser/react'

export default function RootLayout({ children }) {
  return (
    <OutlitProvider publicKey="pk_xxx" autoTrack={false}>
      {children}
    </OutlitProvider>
  )
}

// components/cookie-banner.tsx
'use client'

import { useOutlit } from '@outlit/browser/react'

export function CookieBanner() {
  const { enableTracking, disableTracking, isTrackingEnabled } = useOutlit()

  // Don't show if already tracking (user previously accepted)
  if (isTrackingEnabled) return null

  return (
    <div className="fixed bottom-4 left-4 right-4 bg-white p-4 shadow-lg rounded-lg">
      <p>We use cookies to improve your experience.</p>
      <div className="flex gap-2 mt-2">
        <button
          onClick={enableTracking}
          className="px-4 py-2 bg-indigo-600 text-white rounded"
        >
          Accept
        </button>
        <button
          onClick={disableTracking}
          className="px-4 py-2 border rounded"
        >
          Decline
        </button>
      </div>
    </div>
  )
}

With third-party CMPs

Cookiebot
OneTrust

'use client'

import { useOutlit } from '@outlit/browser/react'
import { useEffect } from 'react'

export function CookiebotListener() {
  const { enableTracking } = useOutlit()

  useEffect(() => {
    const handleConsent = () => {
      // @ts-ignore - Cookiebot global
      const consent = window.Cookiebot?.consent
      if (consent?.marketing || consent?.analytics) {
        enableTracking()
      }
    }

    window.addEventListener('CookiebotOnAccept', handleConsent)
    return () => window.removeEventListener('CookiebotOnAccept', handleConsent)
  }, [enableTracking])

  return null
}

'use client'

import { useOutlit } from '@outlit/browser/react'
import { useEffect } from 'react'

export function OneTrustListener() {
  const { enableTracking } = useOutlit()

  useEffect(() => {
    // @ts-ignore - OneTrust global
    const groups = window.OnetrustActiveGroups || ''
    // C0002 = Performance, C0004 = Targeting/Marketing
    if (groups.includes('C0004') || groups.includes('C0002')) {
      enableTracking()
    }

    // Also listen for changes
    const handleConsent = () => {
      // @ts-ignore
      const updatedGroups = window.OnetrustActiveGroups || ''
      if (updatedGroups.includes('C0004') || updatedGroups.includes('C0002')) {
        enableTracking()
      }
    }

    window.addEventListener('consent.onetrust', handleConsent)
    return () => window.removeEventListener('consent.onetrust', handleConsent)
  }, [enableTracking])

  return null
}

Hooks

useOutlit

The primary hook for tracking events and identifying users.

import { useOutlit } from '@outlit/browser/react'

function MyComponent() {
  const {
    track,
    identify,
    setUser,
    clearUser,
    user,       // User identity helper
    getVisitorId,
    isInitialized,
    isTrackingEnabled,
    enableTracking,
    disableTracking,
  } = useOutlit()

  // Track an event
  track('button_clicked', { buttonId: 'cta' })

  // Identify the user
  identify({ email: 'user@example.com', traits: { plan: 'pro' } })

  // Get visitor ID (null if tracking not enabled)
  const visitorId = getVisitorId()

  // Check if tracking is active
  if (!isTrackingEnabled) {
    return <button onClick={enableTracking}>Accept Tracking</button>
  }
}

Returns

(eventName: string, properties?: object) => void

Track a custom event.

(options: IdentifyOptions) => void

Identify the current visitor.

(identity: UserIdentity) => void

Set the current user identity. Ideal for SPA authentication flows.

() => void

Clear the current user identity (on logout).

object

User identity namespace:

user.identify(options) - Identify the user

() => string | null

Get the current visitor’s ID. Returns null if tracking is not enabled.

boolean

Whether tracking is currently enabled. Will be false until enableTracking() is called when autoTrack is false, while the "auto" region check is pending, or when that check requires consent or fails.

() => void

Enable tracking. Call this after obtaining user consent. Needed when autoTrack is false, or in the default "auto" mode when the visitor’s region requires consent or the region check fails.

() => void

Disable tracking and flush any pending events. Use this when a user declines or revokes consent.

boolean

Whether the tracker is ready.

useTrack

A convenience hook that returns just the track function:

import { useTrack } from '@outlit/browser/react'

function FeatureButton({ featureId }) {
  const track = useTrack()

  return (
    <button onClick={() => track('feature_clicked', { featureId })}>
      Try Feature
    </button>
  )
}

useIdentify

A convenience hook that returns just the identify function:

import { useIdentify } from '@outlit/browser/react'

function LoginForm() {
  const identify = useIdentify()

  const onLogin = async (email, password) => {
    const user = await login(email, password)
    
    identify({
      email: user.email,
      userId: user.id,
      traits: {
        name: user.name,
        plan: user.plan
      }
    })
  }
}

Activation event

Track your value milestone as an ordinary event once it succeeds:

'use client'

import { useOutlit } from '@outlit/browser/react'

function OnboardingComplete() {
  const { track } = useOutlit()

  const handleComplete = () => {
    track('onboarding_completed', { flow: 'onboarding', step: 'completed' })
  }

  return <button onClick={handleComplete}>Complete Setup</button>
}

Choose this event as your activation event in Outlit. The first matching event records activation once for each eligible resolved person and company, independently. Billing status comes from verified integrations such as Stripe. See Customer journey.

Framework examples

Next.js App Router

// app/providers.tsx
'use client'

import { OutlitProvider } from '@outlit/browser/react'

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <OutlitProvider
      publicKey={process.env.NEXT_PUBLIC_OUTLIT_KEY!}
      trackPageviews
    >
      {children}
    </OutlitProvider>
  )
}

// app/layout.tsx
import { Providers } from './providers'

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  )
}

// app/dashboard/page.tsx
'use client'

import { useOutlit } from '@outlit/browser/react'
import { useEffect } from 'react'

export default function Dashboard() {
  const { track } = useOutlit()

  useEffect(() => {
    track('dashboard_viewed')
  }, [track])

  return <div>Dashboard</div>
}

Next.js pages router

// pages/_app.tsx
import { OutlitProvider } from '@outlit/browser/react'

export default function App({ Component, pageProps }) {
  return (
    <OutlitProvider publicKey={process.env.NEXT_PUBLIC_OUTLIT_KEY!}>
      <Component {...pageProps} />
    </OutlitProvider>
  )
}

Remix

Remix renders the root component in the browser, so the provider can live directly in root.tsx (Remix has no server-only component boundary like the Next.js App Router). Use a VITE_-prefixed env var for the public key:

// app/root.tsx
import { Outlet } from 'react-router'
import { OutlitProvider } from '@outlit/browser/react'

export default function App() {
  return (
    <html>
      <body>
        <OutlitProvider publicKey={import.meta.env.VITE_OUTLIT_KEY}>
          <Outlet />
        </OutlitProvider>
      </body>
    </html>
  )
}

Common patterns

Track on mount

Track when a component mounts (e.g., page viewed):

import { useOutlit } from '@outlit/browser/react'
import { useEffect } from 'react'

function ProductPage({ productId }) {
  const { track } = useOutlit()

  useEffect(() => {
    track('product_viewed', { productId })
  }, [productId, track])

  return <div>Product {productId}</div>
}

Track form submission

Track custom form events:

import { useOutlit } from '@outlit/browser/react'

function ContactForm() {
  const { track, identify } = useOutlit()

  const handleSubmit = (e) => {
    e.preventDefault()
    const formData = new FormData(e.target)
    
    track('contact_form_submitted', {
      subject: formData.get('subject')
    })

    identify({
      email: formData.get('email'),
      traits: {
        name: formData.get('name'),
        company: formData.get('company')
      }
    })
  }

  return (
    <form onSubmit={handleSubmit}>
      <input name="email" type="email" required />
      <input name="name" type="text" />
      <input name="company" type="text" />
      <input name="subject" type="text" />
      <button type="submit">Send</button>
    </form>
  )
}

Identify after auth

Prefer the user prop instead. The pattern below works, but using the user prop on OutlitProvider is cleaner and handles the lifecycle automatically. See User identity patterns above. If you can’t use the user prop (e.g., the provider is in a different part of the tree), you can sync manually:

import { useOutlit } from '@outlit/browser/react'
import { useUser } from '@/hooks/use-user' // Your auth hook

function AuthObserver() {
  const { setUser, clearUser } = useOutlit()
  const { user, isLoading } = useUser()

  useEffect(() => {
    if (isLoading) return

    if (user) {
      setUser({
        email: user.email,
        userId: user.id,
        traits: {
          name: user.name,
          plan: user.subscription?.plan
        }
      })
    } else {
      clearUser()
    }
  }, [user, isLoading, setUser, clearUser])

  return null
}

TypeScript

Full TypeScript support is included:

import {
  useOutlit,
  OutlitProvider,
  type OutlitProviderProps,
  type UseOutlitReturn,
  type UserIdentity,
} from '@outlit/browser/react'

// Types are inferred
const { track, identify, setUser } = useOutlit()

// Or explicitly typed
const outlit: UseOutlitReturn = useOutlit()

// User identity type
const user: UserIdentity = {
  email: 'user@example.com',
  userId: 'usr_123',
  traits: { name: 'Jane' }
}

Agents

CLI

Concepts

Outlit SDKs

Examples

Installation

Quick start

Using the hook

Provider configuration

OutlitProvider

Props

Client mode

User identity patterns

Pattern 1: client-side auth (Clerk, Auth0, etc.)

Pattern 2: server-side auth (NextAuth, Lucia, etc.)

With third-party CMPs

Hooks

useOutlit

Returns

useTrack

useIdentify

Activation event

Framework examples

Next.js App Router

Next.js pages router

Remix

Common patterns

Track on mount

Track form submission

Identify after auth

TypeScript

Next steps

Server-side tracking

Identity resolution

​Installation

​Quick start

​Using the hook

​Provider configuration

​OutlitProvider

​Props

​Client mode

​User identity patterns

​Pattern 1: client-side auth (Clerk, Auth0, etc.)

​Pattern 2: server-side auth (NextAuth, Lucia, etc.)

​Consent management

​With third-party CMPs

​Hooks

​useOutlit

​Returns

​useTrack

​useIdentify

​Activation event

​Framework examples

​Next.js App Router

​Next.js pages router

​Remix

​Common patterns

​Track on mount

​Track form submission

​Identify after auth

​TypeScript

​Next steps

Server-side tracking

Identity resolution

Installation

Quick start

Using the hook

Provider configuration

OutlitProvider

Props

Client mode

User identity patterns

Pattern 1: client-side auth (Clerk, Auth0, etc.)

Pattern 2: server-side auth (NextAuth, Lucia, etc.)

Consent management

With third-party CMPs

Hooks

useOutlit

Returns

useTrack

useIdentify

Activation event

Framework examples

Next.js App Router

Next.js pages router

Remix

Common patterns

Track on mount

Track form submission

Identify after auth

TypeScript

Next steps