+```
+
+## Video Tracking
+
+### Video Play
+
+```twig
+
+```
+
+## Scroll Tracking
+
+### Scroll Depth (Throttled)
+
+```twig
+
+ {# Page content #}
+
+```
+
+## Third-Party Integration
+
+### Custom Event from External Script
+
+```html
+
+
+```
+
+## Multiple Events on Same Element
+
+```twig
+
+ {{ product.name }}
+
+```
diff --git a/packages/docs/components/Track/index.md b/packages/docs/components/Track/index.md
new file mode 100644
index 00000000..3fa60665
--- /dev/null
+++ b/packages/docs/components/Track/index.md
@@ -0,0 +1,159 @@
+---
+badges: [JS]
+---
+
+# Track
+
+The `Track` component provides declarative analytics tracking compatible with GTM/dataLayer, GA4, Segment, and custom backends. No custom JavaScript required - tracking is fully defined in HTML/Twig attributes.
+
+## Table of content
+
+- [Examples](./examples.md)
+- [JS API](./js-api.md)
+
+## Usage
+
+Import the component and register it in your application:
+
+```js
+import { Base, createApp } from '@studiometa/js-toolkit';
+import { Track, TrackContext } from '@studiometa/ui';
+
+class App extends Base {
+ static config = {
+ name: 'App',
+ components: {
+ Track,
+ TrackContext,
+ },
+ };
+}
+
+createApp(App);
+```
+
+### Click Tracking
+
+Track user interactions with `data-track:click`:
+
+
+
+
+
+
+:::code-group
+
+<<< ./stories/basic/click.twig
+<<< ./stories/basic/app.js
+
+:::
+
+
+
+### Page Load Tracking
+
+Use `data-track:mounted` to dispatch tracking data when the component mounts (page load):
+
+
+
+
+
+
+:::code-group
+
+<<< ./stories/basic/mounted.twig
+<<< ./stories/basic/app.js
+
+:::
+
+
+
+### Impression Tracking
+
+Use `data-track:view` for IntersectionObserver-based impression tracking:
+
+
+
+
+
+
+:::code-group
+
+<<< ./stories/basic/view.twig
+<<< ./stories/basic/app.js
+
+:::
+
+
+
+### Hierarchical Context
+
+Use `TrackContext` to provide shared data that is merged into all child `Track` components:
+
+
+
+
+
+
+:::code-group
+
+<<< ./stories/basic/context.twig
+<<< ./stories/basic/app.js
+
+:::
+
+
+
+### Multiple Events
+
+Multiple events can be tracked on the same element:
+
+
+
+
+
+
+:::code-group
+
+<<< ./stories/basic/multiple.twig
+<<< ./stories/basic/app.js
+
+:::
+
+
+
+### Custom Events
+
+Listen to CustomEvents from third-party scripts and extract data from `event.detail`:
+
+
+
+
+
+
+:::code-group
+
+<<< ./stories/basic/custom-event.twig
+<<< ./stories/basic/app.js
+
+:::
+
+
diff --git a/packages/docs/components/Track/js-api.md b/packages/docs/components/Track/js-api.md
new file mode 100644
index 00000000..2cb82a05
--- /dev/null
+++ b/packages/docs/components/Track/js-api.md
@@ -0,0 +1,204 @@
+---
+title: Track JS API
+---
+
+# JS API
+
+## Options
+
+### `threshold`
+
+- Type: `number`
+- Default: `0.5`
+
+The IntersectionObserver threshold used for the `view` event. A value of `0.5` means the tracking will trigger when 50% of the element is visible.
+
+```html
+
+ Product Card
+
+```
+
+## Events
+
+Events are defined using the `data-track:[.]` syntax with a JSON payload.
+
+### DOM Events
+
+Any DOM event can be tracked: `click`, `submit`, `change`, `input`, `focus`, `blur`, `scroll`, `mouseenter`, `mouseleave`, etc.
+
+```html
+
+```
+
+### Special Events
+
+#### `mounted`
+
+Dispatches tracking data immediately when the component mounts. Useful for page load data like ecommerce views.
+
+```html
+
+```
+
+#### `view`
+
+Uses IntersectionObserver for impression tracking. The event fires when the element becomes visible based on the `threshold` option.
+
+```html
+
+ Product Card
+
+```
+
+## Event Modifiers
+
+Modifiers can be chained using `.` as a separator:
+
+```html
+
+ View Product
+
+```
+
+### Available Modifiers
+
+| Modifier | Effect |
+| -------------- | ------------------------------------------------------------ |
+| `.prevent` | Calls `event.preventDefault()` |
+| `.stop` | Calls `event.stopPropagation()` |
+| `.once` | Track only once (removes listener after first trigger) |
+| `.passive` | Registers a passive event listener |
+| `.capture` | Registers the listener in capture phase |
+| `.debounce` | Debounces the handler with a 300ms delay |
+| `.debounce` | Debounces with custom delay (e.g., `.debounce500` for 500ms) |
+| `.throttle` | Throttles the handler with a 16ms delay (~60fps) |
+| `.throttle` | Throttles with custom delay (e.g., `.throttle100` for 100ms) |
+
+### Timing Modifiers Examples
+
+```html
+
+
+
+
+
+
+
+
+
+
+
+```
+
+## Custom Events
+
+The Track component can listen to CustomEvents dispatched by other scripts.
+
+### Using `$detail.*` Placeholders
+
+Extract specific values from `event.detail` using the `$detail.*` syntax:
+
+```html
+
+```
+
+If the form dispatches:
+
+```js
+element.dispatchEvent(
+ new CustomEvent('form-submitted', {
+ detail: { email: 'test@example.com', user: { name: 'John' } },
+ }),
+);
+```
+
+The tracking data will be:
+
+```json
+{ "event": "form_submitted", "email": "test@example.com", "name": "John" }
+```
+
+## TrackContext
+
+The `TrackContext` component provides hierarchical context data that is merged into all child `Track` components.
+
+### Options
+
+#### `data`
+
+- Type: `object`
+- Default: `{}`
+
+The context data to merge into child Track components.
+
+```html
+
+
+
+
+```
+
+### Nested Contexts
+
+When Track is nested in multiple TrackContext components, it uses the data from the **closest parent** only:
+
+```html
+
+
+
+
+
+
+```
+
+## Custom Dispatcher
+
+By default, Track pushes data to `window.dataLayer` (GTM). You can customize the dispatcher:
+
+```js
+import { setTrackDispatcher } from '@studiometa/ui';
+
+// Send to GA4 directly
+setTrackDispatcher((data, event) => {
+ gtag('event', data.event, data);
+});
+
+// Send to multiple destinations
+setTrackDispatcher((data) => {
+ window.dataLayer.push(data);
+ fetch('/api/analytics', { method: 'POST', body: JSON.stringify(data) });
+});
+
+// Reset to default (dataLayer.push)
+setTrackDispatcher(null);
+```
+
+## Methods
+
+### `dispatch(data, event?)`
+
+Manually dispatch tracking data. The data is merged with any parent TrackContext data.
+
+```js
+import { getInstanceFromElement } from '@studiometa/js-toolkit';
+import { Track } from '@studiometa/ui';
+
+const element = document.querySelector('[data-component="Track"]');
+const track = getInstanceFromElement(element, Track);
+track.dispatch({ event: 'custom_event', value: 123 });
+```
diff --git a/packages/docs/components/Track/stories/basic/app.js b/packages/docs/components/Track/stories/basic/app.js
new file mode 100644
index 00000000..233bbcea
--- /dev/null
+++ b/packages/docs/components/Track/stories/basic/app.js
@@ -0,0 +1,27 @@
+import { Base, createApp } from '@studiometa/js-toolkit';
+import { Track, TrackContext, setTrackDispatcher } from '@studiometa/ui';
+
+// Custom dispatcher that also updates debug elements
+setTrackDispatcher((data) => {
+ // Push to dataLayer (default behavior)
+ window.dataLayer = window.dataLayer || [];
+ window.dataLayer.push(data);
+
+ // Update debug elements
+ const debugEl = document.querySelector('[data-debug-datalayer]');
+ if (debugEl) {
+ debugEl.textContent = JSON.stringify(window.dataLayer, null, 2);
+ }
+});
+
+class App extends Base {
+ static config = {
+ name: 'App',
+ components: {
+ Track,
+ TrackContext,
+ },
+ };
+}
+
+export default createApp(App);
diff --git a/packages/docs/components/Track/stories/basic/click.twig b/packages/docs/components/Track/stories/basic/click.twig
new file mode 100644
index 00000000..563bb2f2
--- /dev/null
+++ b/packages/docs/components/Track/stories/basic/click.twig
@@ -0,0 +1,13 @@
+
+
+
+```
+
+### Merge order
+
+Script tag content is the base, attributes are merged on top:
+
+```html
+
+
+```
+
+## Context Hierarchy
+
+`TrackContext` components form a hierarchy through **DOM nesting** (parent/child ancestors only). Siblings are ignored.
+
+When a `Track` dispatches, it walks up the DOM collecting all ancestor `TrackContext` payloads. The merge order is outermost first, innermost last (innermost wins on conflicts).
+
+```html
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+## Full Dispatch Flow
+
+When an event fires on a `Track` component:
+
+### Normal flow (no `.no-merge`)
+
+Merge priority (lowest → highest, each layer overrides the previous):
+
+| # | Layer | Source |
+|---|-------|--------|
+| 1 | Context chain | All ancestor `TrackContext` payloads (outermost → innermost) |
+| 2 | Track script content | `
+```
+
+### TrackContext via attributes
+
+```html
+
+
+
+```
+
+### TrackContext via script tag
+
+```html
+
+```
+
+### Combined: script tag + attributes
+
+```html
+
+
+```
+
+### Multiple events with different payloads
+
+```html
+
+
+```
+
+### Empty `data-track:` (no inline JSON)
+
+```html
+
+
+```
+
+## Implementation Changes
+
+### Shared: `resolvePayload(element)` utility
+
+New function used by both `Track` and `TrackContext` to resolve their payload:
+
+```ts
+function resolvePayload(el: HTMLElement): Record {
+ let data: Record = {};
+
+ // 1. Script tag content (if root is