--- url: /reference/items/Track/js-api.md --- # Track JS API ## Components | Component | Destination | | -------------- | ---------------------------------------------------------- | | `Track` | `window.dataLayer.push(payload)` (GTM / GA4) | | `TrackShopify` | `window.Shopify.analytics.publish(payload.event, payload)` | | `TrackContext` | Provides context inherited by descendant `Track`s | `Track` and `TrackShopify` share a common, provider-agnostic base (`AbstractTrack`) and differ only in their [`dispatch()`](#providers) method. ## Events Events are declared with attributes named `data-track:[.modifier…]`. The attribute **value** can be: * **a bare event name** — the shorthand for the common case, avoiding JSON in HTML: ```html ``` * **a JSON object** — merged into the dispatched payload, with the event name under its `event` key. Use this when a single event needs its own structured data (the payload ref and options are shared by every event on the element): ```html ``` * **empty** — the payload then comes entirely from the context, the `payload` ref and/or the `payload` option: ```html
``` Several `data-track:*` attributes can be set on the same element to track independent events. ### Reserved events | Event | Behaviour | | --------- | --------------------------------------------------------------------------------------------------------------------- | | `mounted` | Dispatched once, when the component mounts. | | `view` | Dispatched when the element enters the viewport, via `IntersectionObserver` (see the [`threshold`](#options) option). | Any other name binds a native DOM event (`click`, `mouseenter`, `submit`, a `CustomEvent` type, …). ### Modifiers | Modifier | Effect | | ----------------------------- | --------------------------------------------------------------------- | | `.prevent` | `event.preventDefault()` | | `.stop` | `event.stopPropagation()` | | `.once` | Dispatch at most once (also stops the `view` observer). | | `.passive` | Register the listener as passive. | | `.capture` | Register the listener in the capture phase. | | `.debounce` / `.debounce` | Debounce the dispatch (default `300`). | | `.throttle` / `.throttle` | Throttle the dispatch (default `16`). | | `.detail` | For a `CustomEvent`, merge the whole `event.detail` into the payload. | Example: `data-track:input.debounce500`, `data-track:click.prevent.once`. ## Payload The dispatched payload is deep-merged from the following sources, in increasing priority: 1. **Inherited context** — from ancestor `TrackContext` components (see below). 2. **Component payload** — shared by every event on the element, from a ` ``` Malformed JSON (in an attribute value or a `
``` ## Providers `dispatch(payload, event?)` is the seam that sends the resolved payload to its destination: * **`Track`** — `window.dataLayer.push(payload)`. * **`TrackShopify`** — `window.Shopify.analytics.publish(payload.event, payload)`, guarded when the API is unavailable or the payload has no `event` name. Namespace Shopify event names (e.g. `my_app:add_to_cart`). To send to any other destination (Segment, a custom endpoint, …), extend `Track` and override `dispatch()`: ```js import { Track } from '@studiometa/ui'; export class TrackSegment extends Track { static config = { ...Track.config, name: 'TrackSegment' }; dispatch(payload) { window.analytics?.track(payload.event, payload); } } ```