React SDK

Use @convertmax/react when you want React-specific bindings on top of the base JavaScript SDK. ConvertmaxProvider is the canonical provider export, and createConvertmax from @convertmax/js is the canonical client factory.

Install the packages

Install the React package together with the base SDK:

npm install @convertmax/react @convertmax/js

ConvertmaxProvider initializes the browser client on mount, so browser auto behaviors start without waiting for the first manual track() call.

Wrap your app

Configure the provider with the Convertmax event endpoint:

import { ConvertmaxProvider, useConvertmax } from "@convertmax/react";

function SignupButton() {
  const convertmax = useConvertmax();

  return (
    <button
      onClick={() =>
        void convertmax.track("click", {
          target: "hero_cta",
          page: "https://example.com/pricing"
        })
      }
    >
      Start free
    </button>
  );
}

export function App() {
  return (
    <ConvertmaxProvider
      options={{
        host: "https://event.convertmax.io",
        apiKey: "YOUR_API_KEY",
        autoPage: true
      }}
    >
      <SignupButton />
    </ConvertmaxProvider>
  );
}

autoPage

When autoPage: true is enabled, the browser client automatically emits page_view:

• on the initial page load after initialization
• after history.pushState and history.replaceState
• on back and forward navigation via popstate
• when only the query string changes

Hash-only changes are ignored by default.

Use autoPage for browser route tracking. Use usePageTracking() when you want a manual page-view-style event from a specific component.

Automatic browser behaviors

The underlying published JS client can also automatically:

• detect ad click IDs like gclid, msclkid, ttclid, fbclid, and related campaign identifiers, then emit a cpc event
• classify organic referrers and emit organic
• classify social referrers and emit social
• classify search-engine referrers and emit search when a search term is available
• populate hidden form inputs named cm_visitor and cm_session
• optionally capture Clickfunnels cf_uvid from browser storage when captureCfUvid: true
• detect mobile browsers and include that state in automatic browser events
• respect local opt-out state

Available React helpers

The package includes these React-focused exports:

• ConvertmaxProvider
• useConvertmax()
• usePageTracking(name?, properties?)

If you need to build a client outside React, use createConvertmax() from @convertmax/js.

Send baseline events

After the provider is mounted, track at least a page view and one conversion path event:

import { useConvertmax } from "@convertmax/react";

function Example() {
  const convertmax = useConvertmax();

  return (
    <button
      onClick={() => void convertmax.track("page_view", {})}
    >
      Track page view
    </button>
  );
}

Verify the install

After loading your React app:

1. confirm the provider initializes successfully
2. confirm a page_view event is emitted
3. trigger one tracked event such as click, add_cart, or convert
4. confirm requests are sent to https://event.convertmax.io

Use the Convertmax Chrome Extension to inspect runtime signals and captured requests.