Extensions

Optional auto-tracking features. Off by default to keep the base bundle small. Each extension lives in a chunk that’s lazy-loaded only when you turn it on.

Enable

All extensions

init("proj_xxx", {
  extensions: {
    outboundLinks: true,
    downloads: true,        // or { extensions: ["pdf", "zip"] }
    notFound: true,         // or { pattern: /^404|missing/i }
    dataAttributes: true,
    webVitals: true,        // or { sampleRate: 0.1 } — requires `web-vitals` peer dep
  }
})

Heads up: All extensions emit custom events, so they require a Pro or Growth plan to land in your charts. The SDK still installs the listeners on the free plan, but the resulting events are dropped at ingest.

Catalog

Extension Emits What it does

outboundLinks outbound_click Tracks clicks on links pointing to a different hostname. Properties: url, host, pathname.

downloads download Tracks clicks on links to common file extensions (pdf, zip, dmg, mp4, csv, and more). Properties: url, filename, extension. Pass { extensions: [...] } to override the list.

notFound 404 Detects likely 404 pages by matching document.title. Default pattern: /^(404|page not found|not found)/i. Properties: pathname, title.

dataAttributes any Auto-tracks clicks on data-clamp-event="name". Sibling data-clamp-* attributes become properties. See section below.

webVitals web_vital Captures LCP, CLS, INP, FCP, TTFB via web-vitals. Properties: metric, value, rating (good/needs-improvement/poor), pathname. Install npm i web-vitals as a peer dep.

Extension	Emits	What it does
`outboundLinks`	`outbound_click`	Tracks clicks on links pointing to a different hostname. Properties: `url`, `host`, `pathname`.
`downloads`	`download`	Tracks clicks on links to common file extensions (pdf, zip, dmg, mp4, csv, and more). Properties: `url`, `filename`, `extension`. Pass `{ extensions: [...] }` to override the list.
`notFound`	`404`	Detects likely 404 pages by matching `document.title`. Default pattern: `/^(404\|page not found\|not found)/i`. Properties: `pathname`, `title`.
`dataAttributes`	any	Auto-tracks clicks on `data-clamp-event="name"`. Sibling `data-clamp-*` attributes become properties. See section below.
`webVitals`	`web_vital`	Captures LCP, CLS, INP, FCP, TTFB via `web-vitals`. Properties: `metric`, `value`, `rating` (good/needs-improvement/poor), `pathname`. Install `npm i web-vitals` as a peer dep.

Data attributes Pro

The dataAttributes extension lets anyone on your team wire up tracking without touching JavaScript. Mark any element with data-clamp-eventand Clamp captures a click on it as a custom event. Useful for marketing pages, CMS-driven content, and anywhere a developer isn’t on standby.

Enable

init("proj_xxx", { extensions: { dataAttributes: true } })

How it works

A single delegated click listener is attached to document. When a click happens, Clamp walks up the DOM from the click target and looks for the nearest ancestor with a data-clamp-event attribute. If found, it fires track(eventName, props).

data-clamp-event="name" sets the event name. Required.
Every other data-clamp-* attribute on the same element becomes a property. The data-clamp- prefix is stripped, dashes become underscores.
data-clamp-money-key="amount currency" becomes a Money property. Example: data-clamp-money-total="29.00 USD".
Clicks on child elements still work. <button data-clamp-event="cta"> fires even when the user clicks the icon inside it.

Examples

Simple click

<button data-clamp-event="signup_click">Get started</button>
// → track("signup_click")

With properties

<a
  href="/pricing"
  data-clamp-event="pricing_view"
  data-clamp-source="hero"
  data-clamp-variant="control"
>
  See pricing
</a>
// → track("pricing_view", { source: "hero", variant: "control" })

With Money

<button
  data-clamp-event="checkout_clicked"
  data-clamp-plan="pro"
  data-clamp-money-price="29.00 USD"
>
  Start on Pro — $29/mo
</button>
// → track("checkout_clicked", {
//     plan: "pro",
//     price: { amount: 29, currency: "USD" }
//   })

Wrapping a complex element

<button data-clamp-event="cta_click" data-clamp-location="nav">
  <svg>...</svg>
  <span>Start free</span>
</button>
// Clicks on the svg or span both fire the event — Clamp walks up to the button.

When to use this vs `track()`

Use data attributesfor static markup, CMS content, A/B test variants, and any moment when the person making the change isn’t a developer.
Use track() when the event depends on runtime state (form submission outcome, derived values, async results) or when you want type safety via typed events.

Debug mode

Logs every tracked event, pageview, and flush to the browser console. Useful during install.

init("proj_xxx", { debug: true })
// or
<Analytics projectId="proj_xxx" debug />

[clamp] Initialized { projectId: "proj_xxx", endpoint: "https://api.clamp.sh", ... }
[clamp] track: pageview {}
[clamp] track: signup { plan: "pro" }
[clamp] flush: 2 event(s)

Turn off before deploying to production.

Extensions

Enable

Catalog

Data attributes Pro

How it works

Examples

When to use this vs track()

Debug mode

When to use this vs `track()`