Analytics and Tracking

User-defined Variable

Also called Custom variable, GTM variable

A variable you configure yourself in Tag Manager, reading a value from the page or mapping one value to another.

Quick facts: User-defined Variable

Category
Analytics and Tracking
Also called
Custom variable, GTM variable
Level
Intermediate
Affects
Tag flexibility, reporting detail, container maintainability
Where to see it
Google Tag Manager (Variables, User-Defined), preview mode
In this article4
  1. How a user-defined variable works
  2. Why user-defined variables matter
  3. Where user-defined variables go wrong
  4. How to act on it

How a user-defined variable works

A user-defined variable is one you create because nothing ready-made supplies the value you need. You choose a type, which decides where the value comes from, give it a name, and from then on any tag or trigger in the container can refer to it.

The types fall into three honest groups. Reading types fetch a value that already exists somewhere: in the data layer, in a first-party cookie, in part of the URL, in a JavaScript variable, or in an element on the page. Deciding types transform an input into an output — a constant that holds a value you would otherwise retype in every tag, a lookup table that maps one value to another, a regex table for pattern matching. Then there is custom JavaScript, which runs code you have written and can therefore do anything at all, including damage.

Why user-defined variables matter

A container is only as good as the values it can reach. Once one variable reliably reports which form was submitted, a single tag can serve every form on the site while reports still tell them apart. Nothing has to be duplicated, and adding a form later needs no new tag.

Lookup tables are the quiet workhorse. Mapping a site’s language, brand or market to the right destination account turns a rule that would otherwise live in somebody’s memory into a visible table anyone can read. Constants do the same for identifiers: keep the ID in one place, and changing it is one edit rather than a search through the container.

Where user-defined variables go wrong

Custom JavaScript gets reached for far too early. It runs on the visitor’s device, a small mistake can throw an error on every page, and it is the type most likely to be inherited by someone who cannot read it. Most of the time a data layer value or a lookup table does the same job in a way the next person can maintain.

Naming is the next weakness. Variables called “Untitled Variable” or “dl thing” make a container unreadable within a year, usually just as the person who built it moves on.

Missing defaults cause the subtlest failures. Without one, an absent value passes through as undefined, and the report shows an empty row rather than an obvious signal that something is broken. Cookie-based variables add their own fragility, since a cookie can be cleared, expired or blocked, so a value that works on your machine may be absent on a visitor’s.

How to act on it

Start from the value, not the type. Write down what you need — form name, order value, membership tier — then pick the least powerful type that can supply it. Data layer first, URL or cookie second, custom JavaScript only when there is genuinely no other route.

Prefix names so the list sorts sensibly and the source is obvious at a glance. Give every variable a default that reads as deliberate, such as “not set”, so gaps appear in reporting instead of disappearing. Test in preview with awkward cases as well as easy ones: the logged-out visitor, the page with no product, the form submitted twice. If a container has grown a tangle of undocumented JavaScript variables, an independent Tag Manager review is usually quicker than unpicking it tag by tag.

Do and do not

Do

  • Choose the least powerful type that supplies the value
  • Give every variable a visible default value
  • Prefix names so the source is obvious

Do not

  • Reach for custom JavaScript as a first option
  • Depend on cookies for business-critical values
  • Leave lookup table rules undocumented for colleagues

Questions people ask about this

When should I use a custom JavaScript variable?

Only when no other type can supply the value and a developer cannot add it to the data layer. It runs in the visitor's browser on every page where it is used, so an error affects real people, not just your reports. Where you do use one, keep it short, handle missing values, and leave a comment explaining its purpose.

What is a lookup table variable for?

Mapping one value onto another without writing code. A common use is turning the hostname or language of the current page into the correct measurement or conversion identifier, so one tag serves several sites or markets. The table is visible in the interface, which makes the rule easy to check and easy for a colleague to update.

Do I need a developer to create these variables?

Not to create them, no. Configuring a variable is a point-and-click job inside Tag Manager. You may need a developer for what sits underneath: pushing an order value or lead type into the data layer so a variable has something dependable to read. That underlying work is what separates fragile tracking from tracking you can trust.

Related terms

Found this useful?

Share it, or ask an AI to summarise it

Back to the glossary

Knowing the term is the easy part

Applying it to your own site and budget is the work. Book a call and I will tell you what actually applies to you.