@vskstudio/takt-react

Idiomatic React wrapper for Takt privacy-friendly analytics.

---

A thin, SSR-safe React layer over @vskstudio/takt-core. It never changes the wire payload or the privacy guarantees — it just makes Takt feel native in a React app.

• <Takt> component — drop it once near the root; it boots analytics in a mount effect and provides the instance to the tree.
• useTakt() hook — grab the live instance anywhere; returns a never-throwing no-op before mount or during SSR.
• useTaktEvent() hook & <TaktEvent> component — declarative click tracking.
• <takt-analytics> custom element — framework-agnostic, React-free embed for non-React pages.

Install

pnpm add @vskstudio/takt-react @vskstudio/takt-core

react (^18 || ^19) and @vskstudio/takt-core are peer dependencies.

Quick start — provider + hook

Mount <Takt> once near your root. It fires an initial pageview, wires SPA navigation, and provides the instance to every descendant:

import { Takt } from '@vskstudio/takt-react'

export function App() {
  return (
    <Takt domain="example.com" outbound files={['pdf', 'zip']}>
      <Routes />
    </Takt>
  )
}

Then track custom events from any descendant:

import { useTakt } from '@vskstudio/takt-react'

export function SignupButton() {
  const takt = useTakt()
  return (
    <button
      onClick={() =>
        takt.track('Signup', {
          props: { plan: 'pro' },
          revenue: { amount: '29.00', currency: 'EUR' },
        })
      }
    >
      Sign up
    </button>
  )
}

useTakt() always returns a usable instance: before <Takt> mounts (or during SSR) it hands back a never-throwing no-op, so your handlers never crash.

<Takt> props

Prop	Type	Default	Description
domain	string	location.hostname	Site identifier sent with every event.
endpoint	string	/api/event	Ingestion endpoint.
outbound	boolean	false	Auto-track outbound link clicks.
files	boolean | string[]	false	Auto-track file downloads; pass extensions to restrict.
spa	boolean	true	Track SPA navigations (pushState/replaceState + popstate).
respectDnt	boolean	true	Suppress events when the browser's Do Not Track is enabled.
excludeLocalhost	boolean	true	Suppress events on localhost and private IP ranges.

Config props are read once when <Takt> mounts. Changing them afterwards has no effect — remount the component to reconfigure.

Declarative click tracking

Two equivalent ways to track a click without writing a handler.

useTaktEvent() returns an { onClick } you spread onto any element:

import { useTaktEvent } from '@vskstudio/takt-react'

export function BuyButton() {
  const onBuy = useTaktEvent({ name: 'Buy', revenue: { amount: '9.00', currency: 'EUR' } })
  return <button {...onBuy}>Buy</button>
}

<TaktEvent> wraps a single child and composes its existing onClick:

import { TaktEvent } from '@vskstudio/takt-react'

export function SignupCta({ onClick }: { onClick: () => void }) {
  return (
    <TaktEvent name="Signup" props={{ plan: 'pro' }}>
      <button onClick={onClick}>Sign up</button>
    </TaktEvent>
  )
}

Both resolve the active instance at click time, so they work inside <Takt> or with an init()-driven core setup, falling back to core's default instance otherwise.

Custom element (React-free)

For non-React pages, import the side-effecting ./element entry to register <takt-analytics>. It bundles core and pulls in no React runtime:

import '@vskstudio/takt-react/element'

<takt-analytics domain="example.com" outbound files></takt-analytics>

Privacy attributes (respect-dnt, exclude-localhost, spa) are on by default and only disabled by an explicit "false"/"0". Presence flags (outbound, files) activate when the attribute is present.

Widgets

Thin wrappers over Takt's server-rendered widgets. <TaktBadge> renders an <img> (the badge SVG); <TaktEmbed> renders an <iframe> (the embed dashboard). Both forward standard element attributes (className, style, …).

import { TaktBadge, TaktEmbed } from '@vskstudio/takt-react'

export function Footer() {
  return (
    <>
      <TaktBadge domain="example.com" variant="d" glyph="dash" />
      <TaktEmbed domain="example.com" theme="dark" />
    </>
  )
}

The badge alt defaults to "takt" but is overridable. The embed <iframe> is hardened: it ships sandbox="allow-scripts allow-same-origin" and a fixed referrerPolicy="strict-origin-when-cross-origin", both applied after your props so a consumer cannot weaken them. The optional host prop must be an absolute http(s) URL (validated by core, which reduces it to its origin); src is wrapper-controlled and cannot be overridden.

For dashboards you build yourself, createStats is re-exported from core:

import { createStats } from '@vskstudio/takt-react'

const stats = createStats({ domain: 'example.com' })
const summary = await stats.summary({ period: '7d' })

SSR / Next.js

The main entry ships with a built-in 'use client' banner, and <Takt> boots inside a mount effect, so nothing touches window/document on the server. In the Next.js App Router, render <Takt> from a client component (or the App Router root) and the rest of the API works unchanged. Importing @vskstudio/takt-react/element on the server is a no-op — registration is guarded behind a customElements check.

Privacy

All privacy behavior lives in @vskstudio/takt-core: Do Not Track support, localhost exclusion, opt-in/opt-out consent, and a frozen wire payload. This wrapper never alters any of it.

License

MIT