The options object parameter allows to override the default automatic tracking behavior of Location Taggers APIs.

OptionPossible value
trackClicksboolean | { waitUntilTracked: true} | { waitUntilTracked: WaitUntilTrackedOptions}
trackBlursboolean | { trackValue: boolean}
trackVisibilityboolean | { mode: 'auto' } | { mode: 'manual': isVisible: boolean }
validate{ locationUniqueness: bolean }

All options are optional and can be either omitted or set to undefined to revert to the default values.


Used to customize whether and how click Event Listeners are attached to Tagged Elements.


Some interactions may lead to the current session being closed. For example external links.

To avoid losing those events the waitUntilTracked option can be specified. This will attach a capture Event Listener which will attempt to wait for the Tracker to finish its work before allowing the User Agent to follow its destination.

When setting waitUntilTracked to true we will use some sensible defaults for WaitUntilTrackedOptions.

Custom values can be specified as well:


OptionPossible value
flushQueuetrue | false | onTimeout

In the following example we are instructing our Mutation Observer to attach a Click Event handler that will attempt to wait for up to 3 seconds, polling every 100ms and flushing the TrackerQueue only on timeout.

id: 'external',
href: 'https://www.external.com',
options: {
trackClicks: {
waitUntilTracked: {
intervalMs: 100,
timeoutMs: 3000,
flushQueue: 'onTimeout'


Used to either force or prevent blur Event Listeners being attached to Tagged Elements.

options: { 
trackBlurs: true

// or, to prevent tracking

options: {
trackBlurs: false

Track also input values

To capture values the trackValue option can be specified. This will result in an InputValueContext to be attached to the event.

options: {
trackBlurs: {
trackValue: true


Used to customize whether to track trackHiddenEventEvent and trackVisibleEvent events, either automatically or manually.

Visibility mode:auto

Either trackHiddenEvent or trackVisibleEvent are triggered when Tagged Elements are added or removed to/from the DOM.

options: { 
trackVisibility: true

// or

options: {
trackVisibility = {
mode: 'auto'

Visibility mode:manual

Either trackHiddenEvent or trackVisibleEvent are triggered whenever the isVisible boolean state attribute changes.

options: {
trackVisibility = {
mode: 'manual',
isVisible: boolean

Disable automatic Visibility tracking

options: {
trackVisibility = false


Used to override how the parent of a Tagged Element gets determined. When reconstructing the Location Stack the given parent will be followed instead of the DOM tree.

A practical is to track dynamically placed nodes in the DOM, such as React Portals.

const parentDiv = tagContent({ id: 'section' });

<div {...parentDiv}>

<Modal {...tagOverlay({ id: 'portal-modal', options: { parent: parentDiv } })}>

See Example of Component using Portals for another example.


Used to configure client-side validation.

OptionPossible value


Sometimes the same piece of UI can have mutually exclusive variants, e.g. a menu switching to its mobile version via CSS.

In those cases uniqueness checking can be disabled setting validate.locationUniqueness to false.