betterumami-react

React bindings for BetterUmami analytics.

Install

npm install betterumami-react

Peer dependency: react >= 18.

Usage

import { BetterUmamiProvider, useTrackEvent } from 'betterumami-react';

function Root() {
  return (
    <BetterUmamiProvider websiteId="..." hostUrl="https://analytics.example.com">
      <App />
    </BetterUmamiProvider>
  );
}

function Button() {
  const track = useTrackEvent();
  return <button onClick={() => track('signup-button', { plan: 'pro' })}>Sign up</button>;
}

Props

BetterUmamiProvider accepts every option from @betterumami/core's BetterUmamiConfig plus two explicit props pulled out of the buried defaults:

| Prop | Type | Default | Description | |---|---|---|---| | children | ReactNode | — | Required. | | autoTrack | boolean | true | Enable automatic click/pageview tracking on init. Set false if you only want manual track() calls. | | autoPageview | boolean | true | Fire a pageview on load and on SPA route changes. Set false when mounting the SDK inside a router that already reports its own route changes (e.g. appWithTranslation, appWithTypeScript). | | websiteId | string | — | Required. Website ID from your dashboard. | | hostUrl | string | window.location.origin | | | endpoint | string | /api/send | | | domains | string \| string[] | — | | | excludeSearch / excludeHash | boolean | false | | | doNotTrack | boolean | false | | | tag | string | — | | | credentials | RequestCredentials | 'omit' | | | beforeSend | (type, payload) => payload \| null | — | | | nonce | string | — | CSP nonce for the marker <script>. | | dryRun | boolean | false | Log payloads to console.log instead of POSTing. | | trackPopstate | boolean | true | |

Hooks

| Hook | Returns | |---|---| | useTrackEvent() | track(eventName, eventData?) — stable identity across renders | | useIdentify() | identify(id, data?) |

Imperative exports

import { trackEvent, getSession, track, identify } from 'betterumami-react';

How to tell the SDK loaded

After mount, the underlying core injects a no-op marker into <head> and exposes window.betterumami. Open DevTools → Elements → <head> to confirm, or run window.betterumami.track('devtools-test') in the console.

See @betterumami/core README for full config docs and error-handling behavior.