Variables Guide in Google Tag Manager——Built-In Variables

Table of Contents

Update time: January 14, 2025

This article introduces Built-In Variables

What are Built-In Variables?

Built-in variables are a special category of variables that are pre-created and cannot be customized. You only need to check them to use them, which is very convenient.

Enable Built-In Variables

In GTM, click 「Variables」——「Configure」:

Check it to enable it. Once enabled, you can see it in Variable:

Built-In Variables Categories

Different container types have different built-in variables, such as Web, AMP, and iOS.

This article mainly introduces the Web type, which provides 9 categories and 44 built-in variables.

Utilities

The Utilities type has 6 built-in variables:

Event: Accesses the event key in the dataLayer, which is the name of the current dataLayer event (e.g. gtm.js, gtm.dom, gtm.load, or custom event names).
Environment Name: Returns the user-provided name of the current environment, if the container request was made from an environment “Share Preview” link or from an environment snippet. For the built-in environments, it will return “Live”, “Latest”, or “Now Editing”. In all other cases it returns an empty string.
Container ID: Provides the container’s public ID. Example value: GTM-PHXQ69M
Container Version: Provides the version number of the container, as a string. Example value: 45
Random Number: Returns a random number value.
HTML ID: Allows custom HTML tags to signal if they had succeeded or failed; used with tag sequencing.

Errors

The Errors type has 4 built-in variables:

Error Message: Accesses the gtm.errorMessage key in the dataLayer, which is set by JavaScript Error triggers. This will be a string that contains the error message.
Error URL: Accesses the gtm.errorUrl key in the dataLayer, which is set by JavaScript Error triggers. This will be a string that contains the URL where the error occurred.
Error Line: Accesses the gtm.errorLine key in the dataLayer, which is set by JavaScript Error triggers. This will be a number of the line in the file where the error occurred.
Debug Mode: Returns true if the container is currently in preview mode.

Clicks

The Click type has 6 built-in variables, These will only be used for targeting when setting click events.

Click Element: Accesses the gtm.element key in the dataLayer, which is set by Click triggers. This will be a reference to the DOM element where the click occurred.
Click Classes: Accesses the gtm.elementClasses key in the dataLayer, which is set by Click triggers. This will be the string value of the classes attribute on the DOM element that was clicked.
Click ID: Accesses the gtm.elementId key in the dataLayer, which is set by Click triggers. This will be the string value of the id attribute on the DOM element that was clicked.
Click Target: Accesses the gtm.elementTarget key in the dataLayer, which is set by Click triggers.
Click URL: Accesses the gtm.elementUrl key in the dataLayer, which is set by Click triggers.
Click Text: Accesses the gtm.elementText key in the dataLayer, which is set by Click triggers.

The positions of these Built-In Variables in the source code are as follows:

When tracking click events, triggers are often located using these built-in variablesm, read more ：GA4 Event Tracking Series ⑤ —— Custom Events (Attributes Method)

Forms

The Forms type has 6 built-in variables：

Form Classes: Accesses the gtm.elementClasses key in the dataLayer, which is set by Form triggers. This will be the string value of the classes attribute on the form.
Form Element: Accesses the gtm.element key in the dataLayer, which is set by Form triggers. This will be a reference to the form’s DOM element.
Form ID: Accesses the gtm.elementId key in the dataLayer, which is set by Form triggers. This will be the string value of the id attribute on the form.
Form Target: Accesses the gtm.elementTarget key in the dataLayer, which is set by Form triggers.
Form Text: Accesses the gtm.elementText key in the dataLayer, which is set by Form triggers.
Form URL: Accesses the gtm.elementUrl key in the dataLayer, which is set by Form triggers.

This is only used for form tracking, but form tracking needs to meet two conditions:

HTML must include a <form> tag, ensuring that both the browser and the trigger can recognize it as a form.
There should be at least one <input> or <button> element with its type attribute set to submit for users to submit the form.

History

The History type has 5 built-in variables,

History Source: Accesses the gtm.historyChangeSource key in the dataLayer, which is set by History Change triggers.
New History Fragment: Accesses the gtm.newUrlFragment key in the dataLayer, which is set by History Change triggers. Will be the string value of the fragment (aka hash) portion of the page’s URL after the history event.
New History State: Accesses the gtm.newHistoryState key in the dataLayer, which is set by History Change triggers. Will be the state object that the page pushed onto the history to cause the history event.
Old History Fragment: Accesses the gtm.oldUrlFragment key in the dataLayer, which is set by History Change triggers. Will be the string value of the fragment (aka hash) portion of the page’s URL before the history event.
Old History State: Accesses the gtm.oldHistoryState key in the dataLayer, which is set by History Change triggers. Will be the state object that was active before the history event took place.

These built-in variables need to be used in conjunction with the History change trigger and are usually used for tracking in single page applications.

Videos

The Videos type has 8 built-in variables,

Video Current Time: Accesses the gtm.videoCurrentTime key in the dataLayer, which is an integer that represents the time in seconds at which an event occurred in the video.
Video Duration: Accesses the gtm.videoDuration key in the dataLayer, which is an integer that represents the total duration of the video in seconds.
Video Percent: Accesses the gtm.VideoPercent key in the dataLayer, which is an integer (0-100) that represents the percent of video played at which an event occurred.
Video Provider: Accesses the gtm.videoProvider key in the dataLayer, which is set by YouTube Video triggers. This will be the name of the video provider, i.e. ‘YouTube’.
Video Status: Accesses the gtm.videoStatus key in the dataLayer, which is the state of the video when an event was detected, e.g. ‘play’, ‘pause’.
Video Title: Access the gtm.videoTitle key in the dataLayer, which is set by YouTube Video triggers. This will be the title of the video.
Video URL: Access the gtm.videoUrl key in the dataLayer, which is set by YouTube Video triggers. This will be the URL of the video, e.g. ‘https://www.youtube.com/watch?v=gvHcXIF0rTU’.
Video Visible: Access the gtm.videoVisible key in the dataLayer, which is set by YouTube Video triggers. This will be set to true if the video is visible in the viewport, and false if it is not (e.g. below the fold or in a background tab).

These built-in variables need to be used in conjunction with YouTube video trigger. In addition to these built-in variables, there are other variables in the data layer that can be obtained through data layer variables. Read More：Track Youtube Videos on Google Analytics 4 [2 Easy Ways]

Scrolling

The Scrolling type has 3 built-in variables,

Scroll Depth Threshold: Accesses the gtm.scrollThreshold key in the dataLayer, which is set by Scroll Depth triggers. This will be a numeric value that indicates the scroll depth that caused the trigger to fire. For percentage thresholds, this will be a numeric value (0-100). For pixels, this will be a numeric value that represents the number of pixels specified as the threshold.
Scroll Depth Units: Accesses the gtm.scrollUnits key in the dataLayer, which is set by Scroll Depth triggers. This will be either ‘pixels’ or ‘percent’, that indicates the unit specified for the threshold that caused the trigger to fire.
Scroll Direction: Accesses the gtm.scrollDirection key in the dataLayer, which is set by Scroll Depth triggers. This will be either ‘vertical’ or ‘horizontal’, that indicates the direction of the threshold that caused the trigger to fire.

These variables need to be used in conjunction with the Scroll Depth trigger, read more : Track Page Visit Depth Using the Scroll Depth in GTM

Visibility

The Visibility type has 2 built-in variables,

Percent Visible: Accesses the gtm.visibleRatio key in the dataLayer, which is set by Element Visibility triggers. This will be a numeric value (0-100) that indicates how much of the selected element is visible when the trigger fires.
On-Screen Duration: Accesses the gtm.visibleTime key in the dataLayer, which is set by Element Visibility triggers. This will be a numeric value that indicates how many milliseconds the selected element has been visible for when the trigger fires.

These built-in variables need to be used in conjunction with the Element visibility trigger, read more :「GTM」Using Element Visibility for Form Submission Tracking

The use of Built-In Variables

Built-In Variables have two uses:

Variables in triggers are used to define filters that specify when a particular tag should fire. Example: Fire a pageview trigger when the url variable is “example.com/index.html”.
Variables in tags are used to capture dynamic values. Example: Capture and apply the transaction value and products purchased to a key events tag.

If you don't understand, You can leave a comment below.