Every GTM tag needs data — a GA4 Measurement ID, a transaction value, a page URL. Variables are how that data gets into the tag. Understanding variables is the difference between a GTM container that works reliably and one that silently sends wrong data.
Built-In Variables
GTM includes pre-configured variables that require zero setup. Enable them in Variables → Built-In Variables → Configure.
Page Variables
| Variable | Returns | Use For |
|---|---|---|
Page URL | Full URL including query string | Page-based triggers |
Page Hostname | Domain only (example.com) | Cross-domain detection |
Page Path | Path only (/products/widget) | URL-based triggers |
Referrer | Previous page URL | Referral tracking |
Click Variables
| Variable | Returns | Use For |
|---|---|---|
Click URL | URL of clicked link | Outbound click tracking |
Click Text | Text content of clicked element | Button click tracking |
Click ID | HTML id attribute | Specific element targeting |
Click Classes | CSS classes | Class-based triggers |
Click Element | DOM element reference | Advanced targeting |
Form Variables
| Variable | Returns | Use For |
|---|---|---|
Form ID | HTML id of submitted form | Form tracking |
Form Classes | CSS classes of form | Form targeting |
Form Element | DOM reference | Advanced form handling |
Form URL | Form action URL | Destination tracking |
Other
| Variable | Returns | Use For |
|---|---|---|
Container ID | GTM container ID | Debugging |
Environment Name | Current GTM environment | Staging vs production |
Event | Data layer event name | Event-based triggers |
HTML ID | The custom HTML tag’s ID | Tag sequencing |
User-Defined Variables
These you create yourself. GTM offers many types — here are the ones you’ll actually use.
Data Layer Variable (Most Important)
Reads a value from the GTM data layer. This is how you get ecommerce data, custom dimensions, and application state into tags.
Setup: Variables → New → Data Layer Variable → enter the key name.
Example: Your site pushes dataLayer.push({ event: 'purchase', transactionTotal: 149.99 }). Create a Data Layer Variable with key transactionTotal to use this value in tags.
Nested keys: Use dot notation. For ecommerce.purchase.revenue, set the variable name to ecommerce.purchase.revenue.
Common mistake: The data layer key name is case-sensitive. transactionTotal and transactiontotal are different variables. If your variable returns undefined, check the casing in your data layer.
Constant Variable
A fixed value that doesn’t change. Used for IDs and configuration values you reference in multiple tags.
Example: Create a Constant Variable named GA4 Measurement ID with value G-XXXXXXXXX. Reference it in all GA4 tags instead of hardcoding the ID. When you need to change it, you update one variable instead of 15 tags.
Use for: GA4 IDs, Meta Pixel IDs, Google Ads Conversion IDs, API keys.
JavaScript Variable
Returns the result of a JavaScript expression. The expression must return a value.
Example: Get the current page’s canonical URL:
function() {
var link = document.querySelector('link[rel="canonical"]');
return link ? link.href : document.location.href;
}Use with caution: JavaScript variables run on every GTM event. Complex DOM queries slow down tag firing. Keep them simple.
1st Party Cookie Variable
Reads a browser cookie value. Useful for reading analytics cookies.
Example: Read the _ga cookie to get the GA4 client ID:
- Cookie Name:
_ga
Returns something like GA1.1.1234567890.1234567890.
Used by: Server-side tracking implementations that need to pass cookie values to CAPI endpoints.
Lookup Table Variable
Maps input values to output values. Like a switch statement.
Example: Map page paths to content groups:
| Input (Page Path contains) | Output |
|---|---|
/products/ | Products |
/blog/ | Blog |
/about | About |
| (default) | Other |
Use for: Content grouping, campaign categorization, environment detection.
RegEx Table Variable
Like Lookup Table but uses regular expressions for matching. More flexible, more complex.
Example: Extract product category from URL:
| Pattern | Output |
|---|---|
/products/shoes/(.*) | Shoes |
/products/clothing/(.*) | Clothing |
.* | Uncategorized |
Auto-Event Variable
Reads properties of the DOM element that triggered an event (click, form submission, etc.).
Example: Get the data-product-id attribute of a clicked button:
- Variable Type: Auto-Event Variable
- Variable Component: Element Attribute
- Attribute Name:
data-product-id
Variable Scope and Timing
Variables are evaluated when the tag fires, not when the variable is created. This matters for dynamic values.
Scenario: User loads the page (data layer has pageType: "home"). User clicks a button that pushes dataLayer.push({ pageType: "product" }). A tag fired by the click trigger reads the pageType variable — it gets "product", not "home".
The data layer is a stack, not a dictionary. GTM reads the most recent value for each key. Old values are overwritten by new pushes.
Debugging Variables
GTM Preview Mode
Open GTM Preview → Preview → navigate your site.
Click any event in the debug panel → Variables tab → see every variable’s value at that moment.
If a variable shows undefined:
- The data layer key doesn’t exist (check your site’s data layer pushes)
- The key name has a typo (case-sensitive)
- The data layer push happened AFTER the tag fired (timing issue)
See our GTM debugging guide for step-by-step troubleshooting.
Console Check
In browser DevTools console, type dataLayer to see the current state. Look for your expected keys and values.
Organizing Variables
As your container grows, variables accumulate. Keep them organized:
Naming convention: [Type] - [Purpose]
DL - Transaction Total(Data Layer)JS - Canonical URL(JavaScript)Const - GA4 ID(Constant)Cookie - GA Client ID(1st Party Cookie)
Folder structure: Group related variables in GTM folders:
Ecommerce— transaction values, product data, order IDsConfiguration— platform IDs, API keysPage Data— URL components, content groupsUser Data— user ID, login state
The Variable Checklist
Before publishing a GTM container update:
- All Data Layer variables have correct key names (case-sensitive)
- No JavaScript variables with heavy DOM operations
- Constant variables used for IDs (not hardcoded in tags)
- All variables tested in Preview Mode with real values
- No unused variables cluttering the container (see our GTM audit checklist)
Need help with your GTM setup? Run a free tracking scan — we identify misconfigured tags, broken variables, and missing events automatically.