Clicks

A single delegated click listener on document (capture phase, passive) records click events. Bundle target: under 1 kB gzip.

Install

import { installClickCapture } from '@syntarie/tracking/clicks';
import { send } from '@syntarie/tracking';

const teardown = installClickCapture(send, { mode: 'data-track' });

Modes

mode	Behaviour
'all'	Every click anywhere in the document is captured. Throttled per selector.
'data-track'	Only clicks landing on (or up to 5 ancestors above) an element carrying a data-track attribute are captured.

'data-track' is the recommended default: it keeps event volume bounded and makes intent explicit at the markup level.

<button data-track="signup_cta" data-track-variant="hero">
  Get started
</button>

A click on this button emits:

{
  "type": "click",
  "url": "https://example.com/",
  "ts": 1714665600000,
  "props": {
    "selector": "button.btn-primary",
    "label": "signup_cta",
    "variant": "hero"
  }
}

The data-track-* prefix is stripped — data-track-variant="hero" becomes props.variant.

Selector format

The props.selector is a CSS-ish path of up to 5 levels:

section.hero > div.cta > button.btn-primary

It is intentionally lossy — the goal is to identify the element in analytics queries, not to round-trip a re-selectable DOM path. The path includes tag, leading id (if any), and the first stable class name per level.

Throttle

Each unique selector is throttled to one emit per ~150 ms. Mash-clicking a button does not produce 30 events per second.

Combining with the tracking plan

click events are a free-form custom event from the platform’s perspective — the props.label and props.selector are not in the canonical tracking plan. If you want strict typing for clicks, define them as named events in your plan and emit them via track().