User-defined variable types for web

Create custom user-defined web variables in Google Tag Manager to suit specific requirements that might not already be covered by built-in variables.

To create a new user-defined variable:

In the left navigation, click Variables.
In the User-Defined Variables section, click New.
Click Variable Configuration and select the desired variable type.
Enter configuration options for the selected variable type.
Name the variable. Use a naming scheme that is descriptive of the variable's function, e.g. "Data Layer Variable - Product Name."
Click Save.

Tag Manager supports these user-defined variable types for web:

Navigation
- HTTP Referrer
- URL
Page variables
Page elements
Utilities
User-provided data
Container data

HTTP Referrer

The value is set to the HTTP referer, which is the URL of the previous page that the person visited. For example, if a person navigates to one of your product pages from the home page, the referrer will be the home page. An instance of this variable type is automatically created by Tag Manager, but you can create additional instances if you would like to have expose different parts of the referrer URL.

URL

This type of variable allows you to parse and expose URL components. You can create additional instances to expose different parts of the URL. The URL components you can choose from are: Full URL, Protocol, Hostname, Port, Path, Filename Extension, Query, and Fragment. The input value set for variables of this type is the URL of the current page the user is on (retrieved from document.location). Adjust URL Source to tell Tag Manager to use another variable as the source of the URL value.

Page variables

1st party cookie

This value is set to the value of the 1st party cookie with the name of the domain that the user is currently on. If more than one cookie with same name is deployed on the same domain, the first value will be chosen. This value is the same is if you had called document.cookie from within a page and chosen the first result.

Custom JavaScript

The value is set to the result of a JavaScript function. The JavaScript must take the form of an anonymous function that returns a value. For example, a custom JavaScript variable can be created to convert all instances of the predefined {{url}} variable to lowercase:

function () { return {{url}}.toLowerCase(); }

Data layer

The value is set when data is pushed to the data layer via the dataLayer.push() call:
dataLayer.push({"Data Layer Name": "value"}).

You can specify how Tag Manager interprets dots (".") in the key name:

Version 1: allow dots in key names. For example, for dataLayer.push("a.b.c": "value"), interpret the name of the key as "a.b.c" (i.e. {"a.b.c": "value"}).
Version 2: interpret dots as nested values. For example, interpret dataLayer.push({"a.b.c": "value"}) as three nested levels: {a: {b: {c: "value"}}}.

JavaScript variable

The value is set to the global JavaScript variable you specify. If the value required was not set up in the data layer (see Data Layer variable), and it's not visible in the DOM (see also: DOM Element variable), it might be possible to get the value from a JavaScript variable. Use this variable type if you can find the value in the page's source code as a global JavaScript variable.

Page elements

Auto-Event variable

Captures information about an item that triggered an event (e.g. clicks, form submissions, element visibility, etc.)

Element: Returns the element object. Can be treated like an object for custom JavaScript, e.g. {{Element}}.title, or in CSS selectors, e.g. {{Element}} matches CSS Selector div.foo.
Element Type: Returns the value element.tagName, e.g. "A", "BUTTON", "IMG".
Element Attribute: Specify an attribute name and this option will return the value of that attribute.
Element Classes: Returns the list of classes found in the element's class attribute.
Element ID: Returns the value of the id attribute.
Element Target: Returns the value of the target attribute, e.g. "_blank".
Element Text: Returns the value of the text content of the element.
Element URL: Returns the URL of the element, gathered from the href or action attribute.
History New URL Fragment: Returns the new URL fragment from browser history, e.g. "#summary".
History Old URL Fragment: Returns the old URL fragment from browser history, e.g. "#intro".
History New State: The new history state object, controlled by the site's calls to pushState.
History Old State: The old history state object, controlled by the site's calls to pushState.
History Change Source: Returns the event that caused a history change, e.g. "pushState", "replaceState", etc.

DOM Element

The value is set to the text of the DOM (Document Object Model) element or the value of the specified DOM element attribute. If the desired value is not set up in the data layer (see Data Layer variable), it's possible that the value can be retrieved from the DOM. Use this variable type if you can find the value in the DOM.

If the optional attribute name is set, the variable's value will return the value specified from that attribute (e.g. data-food="cupcake"); otherwise, the value will be the text within the DOM element.

Element Visibility

The value is set based on the visible state of the specified DOM element. Unlike the Element Visibility trigger, a single Element Visibility variable can only report the visibility of a single element. Choose whether to select an element based on the element ID or a CSS Selector. If multiple elements are matched by a specified CSS Selector, the first matched element will be used.

You can choose the output type for this variable:

True / False: A boolean value that indicates whether the selected element is visible when the variable is referenced.
Percent: A percentage value between 0 and 100 that indicates how much of the selected element is visible on screen when the variable is referenced.

If you select True / False as the output type, you can also specify Minimum Percent Visible to indicate how much of the selected element must be visible on screen for the variable to return true.

Utilities

Constant

The value is set to a string you provide. Constant string variables are commonly used when there are multiple tags that use the same account number. See also: Google Analytics Settings.

Custom Event

The value is set to the name of the custom event that was pushed to the data layer.

Environment Name

Returns the name of the environment that is viewed in preview mode.

Google Tag: Configuration Settings

This variable lets you set configuration-level parameters when the Google tag loads.

For example, let's say you publish your website in multiple languages, and want to segment your audience according to the language they read in. You can create a configuration variable with a language parameter and use it across your Google tags, instead of manually updating each tag.

Learn to reuse configuration settings.

Google Tag: Event Settings

This variable lets you set event-level parameters to send additional data with a GA4 event.

For example, suppose you own an online store and you are having a sale. Now, you would like to track how many people use the discount code that you provided them. Instead of adding a discount parameter to each of your tags manually, you can reuse the parameter with a Google tag: Event settings variable.

Learn to reuse configuration settings.

Lookup Table

The value is set according to the instructions in the lookup table. The lookup table contains two columns. (Table is empty to illustrate how data is used later):

When [select variable] equals	Set [this variable] to

The Lookup Table allows you to create a variable for which the value varies according to the value of another variable. This is useful if your website is set up in such a way that the appropriate value (for example, a conversion ID) can be mapped to the URL, DOM element, or other part of the page. In this example, a variable named Conversion ID is created. If the URL contains “/thanks/buy1.html”, the value is set to “12345”; if the URL contains “thanks/buy2.html”, the value is set to “34567”.

When {{url}} contains	Set {{Conversion ID}} to
/thanks/buy1.html	12345
/thanks/buy2.html	34567
/thanks/buy3.html	56789

Random number

The value is set to a random number between 0 and 2147483647.

RegEx Table

A RegEx Table variable is similar to a Lookup Table variable, with the addition of being able to run regular expression patterns for the items you want to match.

For this RegEx Table configuration:

Pattern	Output
`./page[1-3]\.html.`	foo
`./page[4-6]\.html.`	bar
`./page[7-9]\.html.`	baz

The output value of the variable will be as follows:

Matched result	Value
http://example.com/page1.html	foo
http://www.example.com/page1.html	foo
http://example.com/page2.html#detail	foo
http://example.com/page5.html	bar
http://example.com/page5.html?status=new	bar
http://example.com/page6.html	bar
https://example.com/page9.html	baz

RegEx Table lookups run from the top of the list to the bottom. When a match is found, the corresponding output value is returned.

Select Set Default Value to set an output value for when a match is not found.

By default, patterns must match the full input string and are case insensitive. This behavior can be adjusted in Advanced Settings:

Ignore Case: Patterns will match uppercase and lowercase matches without having to build this into the regular expression explicitly.
Full Matches Only: If enabled, patterns must match the entire input. This is equivalent to having start (^) and end ($) anchors implicitly around your pattern. If disabled, patterns will match when they are found anywhere in the input.
Capture Groups and Replace Functionality: If enabled, you can use dollar-sign replacement syntax to include portions of the input (e.g. from capturing groups in the matched pattern) within the output. For example, if the matched regular expression is /(news)/page(2)\.html, you can use $1 to reference the first capture group ("news") and $2 to reference the second capture group ("2").

The use of "Capture Groups and Replace Functionality" with "Full Matches Only" disabled may result in unexpected behavior (e.g. it may return the entire input value with the matched portion replaced.)

User-provided data

Collects contact form information, such as email, phone, name, and address. Specify the information to capture using one of the following modes:

Automatic configuration: Automatically detects form fields on your website and new entries.
Manual configuration: allows you to map existing Tag Manager variables to the corresponding user-provided data fields such as, email, phone number, and name and address.
Code: allows you to specify a Data Layer Variable or Custom JavaScript Variable that returns your structured user-provided data object.

Container Data

Container ID

Returns the ID of the Tag Manager container, e.g. 'GTM-101010'.

Container Version Number

When the container is in preview mode, the container version variable returns the container's preview version number. Otherwise, this variable returns the container's live version number.

Debug Mode

The value is set to true if the container is in preview and debug mode, and false if not.

Was this helpful?

How can we improve it?