data-vb-event

Overview

The data-vb-event attribute turns any interactive element into an analytics tracking point. When the element (or a descendant) is clicked, the Vanilla Breeze analytics runtime fires a single normalised event through Analytics.track() — no JavaScript authored per element, no glue code per page.

Applies to: any element (the runtime uses a single delegated click listener on document).

Requires: vanilla-breeze-core.js (the analytics runtime auto-wires this attribute on boot).

Basic Usage

Put the attribute on any element users can click. The value becomes the analytics event name.

Clicking any of these elements fires one Analytics.track(name, props) call. The runtime is idempotent and safe to put on elements that already have their own handlers.

Event Properties

Add any number of data-vb-event-* attributes to attach named properties. The attribute name is lower-camelised into the props object.

Property values are always strings — the runtime does not parse numbers or booleans. Keep values short and enumerable (categories, IDs, slugs) rather than raw user input.

Event Naming Convention

Vanilla Breeze normalises event names using a category.action_detail pattern. For custom events, follow the same convention so your data groups cleanly in dashboards alongside the auto-wired VB events.

How It Differs from ping

The native ping attribute sends a fixed POST body to a URL on link click. data-vb-event fires a structured event through the analytics pipeline — richer payload, browser-agnostic, works on any element.

The two compose well — use ping on outbound anchors for zero-JS attribution, and add data-vb-event for richer event data when JavaScript is available.

Excluding Elements

To prevent an element (and its descendants) from firing any analytics — including both data-vb-event and the auto-wired VB events — add data-vb-no-track to an ancestor. Exclusion wins over event declaration.

Programmatic API

For events that don't originate from a click — form submissions, timers, custom component state — call Analytics.track() directly.

Both paths share the same envelope, opt-out gates, transport, and URL masking — they are interchangeable and can coexist on the same element.

Opt-Out and Consent

• All data-vb-event firings respect the same opt-out precedence as direct Analytics.track() calls: session opt-out → Global Privacy Control (navigator.globalPrivacyControl) → Do Not Track → app-supplied consent function.
• If any signal indicates opt-out, the event is dropped — no beacon, no console log, no buffer write.
• Authors do not need to check consent themselves.

Accessibility

• The attribute has no effect on the accessibility tree. Screen readers announce the element as they would without it.
• Firing an event does not change focus, visible state, or navigation behaviour.
• Keyboard activation (Enter / Space on interactive elements) triggers the event the same as a mouse click because the runtime listens at document for click.

See Also

• data-vb-no-track — opt an element and its descendants out of analytics
• ping — native link-click tracking
• referrerpolicy — control referrer leakage on analytics requests