Tagging
Tag your web components using data-elb attributes to enable structured event
tracking — no custom JavaScript required.
By adding a few simple attributes to your markup, you can track user behavior such as clicks, views, form submissions, and more.
This technique is especially helpful for component libraries and design systems, where it is important to scale event tagging in a maintainable, reusable way. You can bake tracking into components once, then use them everywhere — without extra code or tracking configuration.
You'll learn how to:
- Define entities, actions, and triggers directly in your HTML
- Add contextual and global properties
- Handle dynamic values, arrays, and type casting
- Link elements across DOM boundaries
- Structure nested data automatically
If you're looking for a lightweight, declarative way to implement analytics
and event tracking, data-elb tagging is your foundation.
Concept
Tag a page...
... to get a structured event as a result:
You are entirely free to define naming conventions.
Entity & action
You define the entity scope by setting the data-elb attribute with the
name of an entity to an element, e.g. data-elb="promotion". The default entity
is page when no data-elb is set.
An action can be added by setting one of the following attributes on the same level or child elements in combination with a matching trigger:
data-elbaction- applies action to the nearest entity onlydata-elbactions- applies action to all entities in the DOM hierarchy
Both attributes use the same syntax, e.g., data-elbaction="visible:view" or
data-elbactions="click:select" to fire events when triggered.
The behavior of data-elbaction changed in @walkeros to apply to nearest entity
only. For the previous @elbwalker "all entities" behavior, use
data-elbactions. See the
Migration Guide for
details.
To define the entities' properties, set the composited attribute
data-elb-ENTITY with the key and value, e.g.
data-elb-promotion="name:tagging is fun;position:overlay".
Triggers
There is a bunch of pre-built triggers. You don't have to deal with event listener or mutation observer initialization.
| Trigger | Definition |
|---|---|
| load | after loading a page when DOM is ready |
| click | when an element or a child is clicked |
| impression | after an element has been in the viewport for at least 50% for one second |
| visible | each time an element re-enters the viewport after being out of view |
| hover | each time the mouse enters the corresponding element |
| submit | on valid form submission |
| wait(ms) | waits ms seconds (15 seconds by default) until triggering |
| pulse(ms) | recurring trigger every ms seconds (15 seconds by default) if the page is not hidden |
Trigger names are predefined and to be selected from the list, while the
action can be an arbitrarily defined name.
Abbreviation
If the trigger and action values are equal, e.g. for click events, you can shorten the implementation:
Parameters
Some triggers require more information during initialization, while others accept optional parameters. The scroll trigger needs to know the percentage a user scrolls down, a wait trigger the number of milliseconds until the action gets triggered. Use brackets behind the trigger to pass that information.
Action filter
At some point, you might want to nest one entity inside another. To prevent an
action to trigger unwanted entities, you can restrict the action to a specific
entity by adding the name, e.g. data-elbaction="load:view(product) or
data-elbactions="load:view(product)". If the trigger event gets called, the
result will only include the property values from the specific entities.
Up-bubbling click trigger
By clicking an element, the event bubbles up to the body element. If the walker
finds a data-elbaction with the click trigger, it will fire the action. Often,
the image or a whole div-block gets clicked, not the parent a-element. Using the
bubbling-up flow, the walker still triggers the actions for you.
The click trigger uses the bubbling-up process. It will not work with stopPropagation or preventDefault.
Linking elements
Use the data-elblink tag to extend the scope of an entity by elements placed
somewhere else (like modals). Specific IDs connect linked elements. They are
hierarchically and can either be a parent or a child.
The second element is the parent, triggering the visible action for the
info visible event. There can be multiple children, but there is only one
parent element per ID.
data-elb, data-elbaction, data-elbcontext, data-elbglobals, and
data-elblink are reserved attributes, whereas data-elb-* attributes may be
arbitrary combinations based on the related entity name. Actions and properties
can be set anywhere inside an elb scope.
Spaces in entities, e.g., "shopping cart" or actions, e.g., "add to cart" will be replaced by underscores to "shopping_cart" and "add_to_cart".
Spaces in property values are no problem, e.g. "category: 'summer sale'" works
fine. But it is better to set them in quotes when doing so or when using
symbols, especially : or ;
Data
Basic attributes
To specify data, use the name of the entity. The data attributes have to be
inside of the entity scope or a parent.
Hierarchy
There is a hierarchy for the data properties, where the order defines which
values to use for similar keys. Based on the triggering action element, the
closest ones or parent values will be preferred over the others.
Based on which element gets clicked, the event will contain the following data
- family:
{ key: 'baz' }, the last found data-property - parent:
{ key: 'foo' }, a direct data-value - child:
{ key: 'bar' }, direct value closer than the parent - sibling:
{ key: 'foo' }, no value specified, so it takes the parent's value
Type casting
Property values will be cast to their type, supporting string, number & boolean.
Multiple attributes
Browsers override duplicate attributes. Hence an element can only have one
data-elb, data-elb-ENTITY, and/or data-elbaction attribute at a time.
Nevertheless, it’s possible to define multiple entities, properties, and/or
actions within one attribute using quotes and semicolons. A semicolon splits
key-value pairs. Therefore, it’s necessary to escape values that contain a
semicolon. Quotes are here to meet your needs. To prevent a mistaken
value-split, use single quotes.
If a single quote is part of the value, escape it with a backslash:
The semicolon can be used as a separator to list multiple values inside of a
data-elb or data-elbaction attribute.
Dynamic field values
You might want to measure dynamic field values, e.g. the quantity of a product
or the value of the selected element. Use a # at the beginning, followed by
the attribute name to access the value of the element attribute.
To capture a selected option from a list, use elb-ENTITY="KEY:#selected" to
get size:20L
Arrays
To use array types, add the [] suffix to a property's name, such as
size[]:m. It will generate de-duplicated data properties.
Generic properties
Leave the entity name empty (only data-elb-) to add the property to any
related entity. Explicitly named properties are preferred over generic ones.
Explicit properties are preferred over generic ones.
Globals
There might be properties that don't belong to just one event but to all
events on a page. Those properties are called globals and will be
collected once, right before the first event, got fired. Globals are
arbitrary, like the data property. What is unique about them is that you can
define them anywhere on a page using the data-elbglobals attribute.
This example will lead to the following event:
For performance reasons, the globals are only collected once per run.
Context
Context doesn't work like globals for every event, but is helpful information for every framing context an event is embedded in. A context could be a position, a test, or specific components for example.
The context properties are tuples with the value and an index, starting at the
closest parent ([value, index]). Access them via event.context.key[0].
At elbwalker we often use context for predefined journeys and stages to measure events along a specific user journey in structured way.
Nested entities
A data-elb entity within another data-elb entity is called a nested
entity.
The walker algorithm runs through nested entities and treats them like regular entities by gathering all related information. Nested entities are accessible in the nested array of each event. Each element is a regular entity.
This example will lead to the following event on load:
Nested entities that are nested inside another entity will be captured on both levels.
Nested entities are not available for auto-captured page view events.
Learn more about the walkerOS event model in our documentation.