Manage variables in Matomo Tag Manager

Cloud On-Premise

A variable is a placeholder that returns a dynamic value when a tag or trigger is executed. You can add variables to tags and triggers to pass dynamic data instead of fixed values. The values collected by variables are then stored and can be used in your reports.

The value returned depends on the context, such as the current page URL, referrer, or screen size. For example, if you use a fixed event name like Event Name = page_view, every event will be recorded as page_view. It does not identify which page the event came from.

If you use a variable, Event Name = {{PagePath}}, then the value changes based on the page, for example, /home, /pricing, /contact

Add variables to tags and triggers

When configuring tags and triggers, the angle bracket icon <> next to an input field indicates variables can be inserted.

Click the icon to select the required pre-configured or user-defined variable.

select variable in mtm

Note: The curly brackets are always required to reference a variable.

You can also combine multiple variables with custom text to build a structured value, for example, for a page URL https://example.com/pricing#plans

This creates a dynamic value where each part is resolved at runtime:

myprefix/{{PagePath}}#{{PageHash}}moretext

Displays in the report as:

myprefix//pricing#plansmoretext

Pre-configured variables

Matomo Tag Manager has a set of preconfigured variables that you can use without any configuration.

  1. To view them, open your Tag Manager container and go to Variables.
  2. Scroll down to Pre-configured variables.
    preconfigured variables in mtm

These variables return common values automatically, such as page information, clicks, or SEO data.

Example

To track how many H1 elements are present on each page, use a pre-configured variable, such as {{SeoNumH1}}, and assign it to a custom dimension in your tag configuration.

When the tag is triggered, the variable returns the number of H1 elements found on the page. This value is sent with the request and stored in your reports, where you can see how many H1 elements were detected per page.

mtm custom report

If you need to modify or transform these values, create a user-defined variable or use a Custom JavaScript variable.

User-defined variables

User-defined variables allow you to collect and control data based on your specific requirements. Matomo provides multiple variable types that you can configure, such as a DOM Element (for values from the page), Data Layer Variable, or meta tag values.

To create a user-defined variable:

  1. Go to Variables and click Create New Variable.
  2. Select a variable type and configure the settings based on where the data is located.
    mtm variable types

Once created, the variable can be selected from the variable picker and reused across tags, triggers, and other variables.

Example

To track the publishing date of an article stored in a DOM element, you can create a DOM Element variable.

<article class="post">
 <header class="entry-header">
 <h1 class="entry-title">Example blog post</h1>
 </header>

 <footer class="entry-footer">
 <span class="posted-on">
 Posted on
 <a href="/example-blog-post/" rel="bookmark">
 <time class="entry-date published" datetime="2026-05-06T10:00:00+00:00">
 6 May 2026
 </time>
 </a>
 </span>
 </footer>
</article>

The CSS selector would be .entry-date.published:

dom element variable

When the tag is triggered, the variable reads the value from the page and returns it. You can then send this value to a custom dimension for reporting.

Advanced settings: Default value and lookup table

Advanced settings allow you to control how a variable behaves when it returns a value.

In the example below, a URL Variable extracts the host name and applies additional logic using advanced settings.

  • The default value is used if the variable does not return a value.
  • The lookup table maps specific host names to predefined values.

You can then call this variable within your Matomo tag through the Matomo Configuration Variable. As a result, you will only need one container to send data to all your websites which will save you heaps of time in terms of tag deployment.

While advanced settings are available for user-defined variables, pre-configured variables cannot be modified directly. To apply a default value or lookup table to a pre-configured (or user-defined) variable, wrap it in a Custom JavaScript variable.

Pre-configured and user-defined variables extend what is possible by collecting, transforming, and reusing data specific to your setup.