Custom Templates

Custom HTML tags execute arbitrary JavaScript in the user’s browser with no guardrails. Custom Templates do the same job, but in a sandboxed JavaScript environment with declared permissions, a built-in test runner, and the ability to share and receive updates through the Community Template Gallery.

If you are writing Custom HTML tags for third-party vendor integrations, you should be writing Custom Templates instead. The sandbox is not a limitation — it is a feature. It makes your templates auditable, testable, and safer for the organizations that deploy them.

Tip

Custom Templates require comfort with JavaScript. This section assumes you already know how to write Custom HTML tags and understand GTM’s variable system. If you’re new to GTM, start with Tags, Triggers, and Variables.

The template system

Sandboxed JavaScript APIs Complete reference for every API available in the template sandbox — what's available, what's not, and why the restrictions exist.

Template Permissions and Security The permissions model, auto-detection, Template Policies, and what a malicious template could do without proper governance.

Building templates

Building Tag Templates Complete walkthrough: field types, code structure, permissions, and building a real vendor pixel template from scratch.

Building Variable Templates Creating custom variable templates for data transformation, cookie parsing, and server-side async lookups.

Building Client Templates Server-side GTM client templates — claimRequest(), event model construction, response handling, and webhook receivers.

Testing Custom Templates Writing and running tests with runCode(), assertThat(), and mock() — template testing that actually catches bugs.

Community Gallery

Community Gallery Guide How to evaluate, install, and maintain templates from the Gallery — including which ones are actually worth using.

Publishing to the Gallery Repository structure, the .tpl format, metadata.yaml, submission requirements, and common rejection reasons.

Custom Template vs. Custom HTML

The choice is not always obvious. Here is how to think about it:

Use Custom Templates

• You are building something you plan to reuse or share
• You want the permission model to make the implementation auditable
• You are building a server-side client or variable template
• You want a built-in test runner
• You are distributing to containers you don’t control

Use Custom HTML

• You need a quick one-off implementation
• You require browser APIs the sandbox doesn’t expose directly
• The tag fires in a single container you control fully
• Speed of implementation matters more than long-term maintainability

In practice, if the Custom HTML tag you are writing could be installed by someone else — even just another developer at your company — it should be a template. The declarative permissions alone make code review dramatically easier.

A note on server-side templates

Server-side GTM uses the same template system with additional APIs. Client templates, which are unique to sGTM, are covered in Building Client Templates. Variable templates for sGTM follow the same structure as client-side variable templates but support async patterns with Promises, covered in Building Variable Templates.

The sandboxed JavaScript APIs differ between client-side and server-side contexts. The Sandboxed JavaScript APIs article covers both, with clear labeling of which APIs are available where.