Google Tag Manager: The Lookup Table Macro

Introducing the Lookup Table macro in Google Tag Manager.

Having just come hot of the press with my latest article on GTM and Content Grouping which, to my delight, Bounteous had written an amazing tutorial on earlier, Brian Kuhn and the amazing Google Tag Manager development team came out with another incredible new feature: The Lookup Table Macro.

In software engineering, a lookup table is an array which takes away a layer of complexity in runtime computation, and replaces it with a simple value assignment based on array indexing. To put it simply, a lookup table looks through an array of source values, and assigns a value to the target depending on what the source value is. Well, maybe it’s easiest to show it in an image:

This is probably the most simple use case for the lookup table. The range of source values is derived from the custom JavaScript macro {{post_publish_date_month}}, which returns the month when the article the visitor is browsing was published. The lookup table goes through the possible values of the source macro, and it uses these values to assign the literal month name to the target macro, {{Post publish month}}.

NOTE! The source value (i.e. “When {{macro}} equals”) is case-sensitive!

Why use lookup tables

So why resort to a lookup table, when you can just add simple predicate logic to your custom JavaScript, and have it return the month name directly? Well, sure, you could do that, and in most cases it would be just fine.


A lookup table, just like macros in general, removes a layer of complexity from your code and replaces it with increased flexibility. Because you take away a transformation from the source (i.e. transliteration of the numerical month to the written month name), you are free to use the numerical month elsewhere in your computations.

Also, a lookup table is an indexing operation and not strictly a calculation, so the runtime processing power it requires is significantly reduced when compared to having your scripts do all the work. With a large setup, where lookup tables might go through a huge number of source and target operations, you’ll end up with less code, less computation, and a nice and flexible framework for value assignment in your macros.

To keep the operation as light as possible, you can only check for equation, e.g. “if {{target macro}} equals something, then…”. I actually asked Brian about this, and he replied:

So if you want to see some other ways of evaluating the source value before assigning a target value, you’ll have to wait and see what the GTM team come up with. I guess it will be some combination of rule + lookup table to keep the setup as simple as possible.

Naturally, you can refer to your lookup table macros in Custom HTML tags and Custom JavaScript macros as well, so you’ll increase the modularity of your code.

Use cases

Let’s put it this way. Any time you need to do a simple “if X is Y then Z” evaluation based on a range of values, you could do so with a lookup table. Let’s start with a simple one.

Multi-account or multi-property container

If you have a single container deployed across many Google Analytics accounts or properties, you’ll come across the problem of assigning the correct tracking code to your tags. You could do it with a unique tag for each deployment, a unique rule for each tag, and a bunch of macros and custom HTML code to check the correct account, but that will soon turn into a veritable noodle-o-rama of a setup.

Relax. Use a lookup table:

Filetype defines event category

This is an example of using macros in the lookup table itself. I have a custom JavaScript macro, which checks the filetype of the link that was clicked. It uses the gtm.element auto-event variables used in auto-event tracking. See how I use a macro in the target value field? That’s how flexible this is. You can create a framework or infrastructure of macros, and come up with something really complex with very simple processing.

Be sure to follow the great Carmen Mardiros from Clear Clues to find out (hopefully soon) about applications of complex indexing logic using macro-based syntax.

More auto-event madness

Another nice use case for auto-event tracking is to set your event parameters depending on what type of auto-event interaction took place. For example, if a link was clicked, I’d want my event action to be the URL of the clicked link. If any click occurred, I want my event action to be the tag type (i.e. DIV or IMG or SPAN etc.) of the clicked element. And if a form was submitted, I’d want my event action to be the ID of the form. Like so:

Then you can just use a single event tag to send your different auto-event hits, with a trigger rule like “{{event}} equals OR {{event}} equals gtm.linkClick OR {{event}} equals gtm.formSubmit”.


The lookup table macro is designed to help you actually create a logical infrastructure for your GTM deployment. It also increases flexibility, since you can cross-reference lookup macros in your tags and other macros. I’m a huge advocate of macros in general, because the less you hard-code into your custom tags the better.

There’s no limit to the number of rows in a lookup table (other than general GTM data set limitations). I know that there’s also an import feature on the roadmap, so you can import your own, pre-defined lookup tables into the system. Mapping classifications from one data set to another will be something that especially large GTM implementations will benefit from.

Finally, I couldn’t agree more with Eric Erlebacher:

The GTM dev team is on a roll right now, and I hope it doesn’t stop anytime soon.