GTM has over 20 built-in variable types plus the ability to create custom JavaScript variables. Choosing the wrong variable type for a given situation creates fragile tracking implementations that break when page structure changes, require excessive maintenance, or fail silently on certain pages. This guide covers every major GTM variable type, the specific use cases each is designed for, and the decision framework for choosing between them when multiple options could work.

Data Layer Variable

Data Layer Variables are the most reliable variable type in GTM and should be your default choice whenever your development team can push data to the dataLayer. A Data Layer Variable reads a value from the dataLayer by key name. For nested objects, use dot notation: ecommerce.purchase.transaction_id reads the transaction_id nested under purchase under ecommerce. For arrays, use bracket notation: ecommerce.items.0.item_name reads the item_name of the first element in the items array.

The advantage of Data Layer Variables over DOM-scraping alternatives is stability. The dataLayer is an intentional contract between your developers and GTM — when the page structure changes, the dataLayer push is updated deliberately. DOM elements change frequently as a side effect of design changes, and JavaScript variables on the page may be renamed or removed without anyone considering the impact on GTM.

DOM Element Variable

DOM Element Variables read text content or attribute values from HTML elements using CSS selectors. Use them when you need to capture data that is visible on the page but is not available in the dataLayer — product prices displayed in the page content, form field values, or confirmation message text. The variable type lets you specify whether to capture the element’s text content or an attribute value (like href, data-product-id, or value).

DOM Element Variables are inherently fragile because they depend on specific CSS selectors remaining stable. A redesign that changes class names or element hierarchy breaks the variable silently. Use DOM Element Variables as a last resort when dataLayer pushes are not feasible. When you must use them, prefer stable attributes (IDs, data attributes) over class names, which change more frequently.

JavaScript Variable

JavaScript Variables read global JavaScript variables from the page’s window object. Use them to read values that your application sets on the window object — window.userId, window.pageType, or any other global your developers expose intentionally. The variable name field should be just the property name without “window.” — to read window.userId, enter userId as the variable name.

JavaScript Variables are appropriate when the value is already exposed as a global but a full dataLayer push is not implemented. They are more stable than DOM Element Variables but less stable than Data Layer Variables because globals can be set at different points in page execution, and GTM’s evaluation timing may read the variable before the application sets it. Test carefully with GTM Preview to verify the variable is populated when your trigger fires.

Custom JavaScript Variable

Custom JavaScript Variables execute a JavaScript function and return its result. This is the most powerful variable type — it can compute derived values, transform other variable values, read and process DOM content, make conditional logic decisions, and return any JavaScript value. The function must use the return statement to provide a value:

// Custom JavaScript Variable example
// Returns page category based on URL path
function() {
  var path = window.location.pathname;
  if (path.indexOf('/blog/') !== -1) return 'blog';
  if (path.indexOf('/product/') !== -1) return 'product';
  if (path.indexOf('/checkout/') !== -1) return 'checkout';
  if (path === '/' || path === '') return 'homepage';
  return 'other';
}

Use Custom JavaScript Variables when you need logic that no other variable type provides: combining multiple data sources, transforming string formats (converting a price string “$19.99” to a number 19.99), or computing derived dimensions (calculating days since first visit from two date fields).

Lookup Table and RegEx Table

Lookup Table Variables map input values to output values using exact string matching. RegEx Table Variables do the same but use regular expressions for matching. Use these when you need to translate raw values into human-readable labels: mapping UTM source values to channel names, converting product IDs to product categories, or translating page URL patterns to page type labels. Both variable types are more maintainable than equivalent Custom JavaScript Variables for simple mapping logic because the mappings are visible in a table format in the GTM interface and can be edited without touching JavaScript code.

Auto-Event Variables

Auto-Event Variables capture properties of the DOM element that triggered a GTM trigger — the element’s text, href, classes, ID, or target. These variables only return useful values in the context of a trigger that fires on a DOM interaction (click, form submission, element visibility). They return undefined when evaluated in other contexts. Use Click Text and Click URL variables with click triggers to capture which link a user clicked without needing specific dataLayer pushes. Use Element Visibility variables with Scroll Depth triggers to capture which element became visible when a user scrolled to it.