How to Set Up Custom Dimensions in Matomo: A Complete Guide

Standard web analytics tools are designed to answer standard questions. They excel at telling you how many people visited, where they came from, and what pages they viewed. This is baseline, commodity-level data. But to generate strategic insights, you must answer specific, high-value questions. You must move from “what” to “so what.” How many “Premium Members” viewed the new feature page versus “Free Trial” users? Which blog authors drive the most goal conversions? What content categories are most popular with visitors from your target industry?

Default Matomo reports, with dimensions like “Browser” or “Country,” cannot answer these questions. To get these answers, you must use custom dimensions.

A custom dimension is a data container you create to track information that is specific to your website and your business logic. Think of default analytics as a filing cabinet that comes with pre-labeled drawers: “Pageviews,” “Visitors,” “Sources.” This is useful, but limited. Custom dimensions are the equivalent of giving you a tool to add new, blank drawers to that cabinet. You can label these new drawers whatever you need: “Membership Status,” “Page Author,” “SaaS Plan,” or “Content Type.” You are no longer limited by the default setup; you are customizing the data model itself.

This capability is the bridge between generic traffic reporting and true business intelligence. Without custom dimensions, your users are largely anonymous data points. By implementing custom dimensions, you enrich every visit and every action with context. You can segment your reports by the user attributes and content metadata that actually matter to your organization. This allows you to stop making assumptions and start making data-driven decisions based on precisely segmented user behavior.

Before we proceed, we must address a critical technical point. You may have seen references to “Custom Variables” in older Matomo documentation. Let’s be unequivocally clear: Custom Variables are deprecated. They are an older, less efficient feature that should not be used for any new implementations. The Matomo team has replaced them entirely with custom dimensions. Why? Because custom dimensions are superior in every significant metric. They are more efficient, they process reports much faster, they are easier to segment in the Matomo UI, and they have a higher character limit (255 vs. 200). If you are still using Custom Variables, your priority should be migrating them. For all new tracking, you will exclusively use custom dimensions.

This guide will show you the correct, modern way to set up and deploy these powerful tools.

Main Concepts: Understanding Scope and Limits

Before you write a single line of code or click a button in the Matomo admin panel, you must understand the foundational theory behind custom dimensions. A failure to grasp this core concept, specifically “scope,” is the single most common reason for a failed or incorrect implementation. Setting up custom dimensions is not just a technical task; it is an architectural one. You are deciding what your data is attached to.  Note custom dimensions are also found in Google Analytics 4 and is discussed in this post.

The Most Critical Decision: Visit Scope vs. Action Scope

Every custom dimension you create must be assigned one of two scopes: “Visit” or “Action.” This choice is permanent for that dimension slot, and it fundamentally changes what the data represents.

Visit Scope

• Definition: A Visit scope custom dimension attaches its value to the entire visit or session.
• Behavior: Think of this as a name tag that a visitor wears for their entire trip to your website. You can only store one value per visit. If you try to set a new value during the same visit, the last value set will overwrite all previous ones for that whole visit.
• Example: A visitor arrives on your site as a “Guest.” You set a Visit scope custom dimension (ID 1) with the value “Guest.” The visitor then logs into their account. You set the same custom dimension (ID 1) with the value “Premium-Member.” When you analyze the reports, that entire visit—from the first pageview to the last—will be tagged as “Premium-Member.” The “Guest” value is gone.
• Common Use Cases: This scope is perfect for attributes that describe the visitor or the session as a whole.
  • User Role: “Guest,” “Logged-In,” “Editor,” “Admin.”
  • Persona: “Developer,” “Marketer,” “Decision-Maker.”
  • Lead Status: “New Lead,” “MQL,” “SQL,” “Customer.”
  • A/B Test Variation: “Variation A,” “Variation B,” “Control.”
  • SaaS Plan Level: “Free-Trial,” “Bronze-Plan,” “Enterprise.”

Using Visit scope custom dimensions allows you to segment your entire Matomo reporting suite by these high-level groups.

Action Scope

• Definition: An Action scope custom dimension attaches its value to a single, specific action. An “action” in Matomo is typically a pageview, but it can also be an event, a download, or an outlink.
• Behavior: This is not a name tag for the visitor; it is a price tag on an item in a store. Each item (or action) gets its own, independent tag. A visitor can trigger multiple Action scope custom dimensions with different values all within the same visit.
• Example: A visitor lands on a blog post titled “Our Q4 Results.” You set an Action scope custom dimension (ID 2) with the value “John-Doe” (the author) and another (ID 3) with the value “Announcements” (the category). In the same visit, the user clicks to another article, “5 Tips for Marketers.” You set custom dimension 2 to “Jane-Smith” and custom dimension 3 to “Marketing-Tips.”
• Common Use Cases: This scope is essential for metadata related to your content or events.
  • Page Author: “John-Doe,” “Jane-Smith.”
  • Article Category: “Technology,” “Marketing,” “Case-Studies.”
  • Published Date: “2024-10-23.”
  • Content Length: “Short-Read,” “Long-Form.”
  • Page Type: “Blog-Post,” “Product-Page,” “Landing-Page.”
  • Event Attribute: The name of a video played or a file downloaded.

Understanding this distinction is the most important step. If you use a Visit scope for “Page Author,” you will only know the last author the person viewed, which is useless. If you use an Action scope for “User Role,” your reports will be incorrect, as the data will only be attached to a single pageview, not the whole visit. Choose your scope with precision.

Prerequisites and Data Limits

Now that you understand scope, there are several technical constraints and questions to ask before you begin implementation.

• Administrative Permissions: You cannot create or manage custom dimensions unless your Matomo user account has “Write” or “Admin” access for the specific website (property) you are working on. A “View” level user can see the reports, but cannot create the dimensions.
• Default Limits: Matomo does not grant you an unlimited number of custom dimensions.
  • Matomo On-Premise: By default, you are limited to 5 custom dimensions of Visit scope and 5 custom dimensions of Action scope.
  • Matomo Cloud: The limits are typically higher, often 15 custom dimensions per scope, giving you 30 total.
• Increasing Limits (On-Premise Only): If you are running your own instance of Matomo and the default of 5 is not enough, you can increase it. This is an advanced task that requires command-line access to your server. The command is:./console customdimensions:add-custom-dimension –scope=visit –count=5This command, for example, would add 5 new slots to the Visit scope.
• Value Character Limit: This is a frequent point of failure. The value you send to any custom dimension (e.g., “Premium-Member”) is automatically truncated at 255 characters. If you send a 300-character string, Matomo will save the first 255 characters and discard the rest. This will result in corrupted, incomplete data in your reports. Ensure all values you send are clear, concise, and well under this limit.

With the theory of scope and limits understood, we can now proceed to the practical, step-by-step implementation.

How to Set Up Custom Dimensions in Matomo (Step-by-Step)

The process of activating custom dimensions is a two-stage process. This is a critical concept.

1. Creation: You must first create the dimension in the Matomo user interface (UI). This tells Matomo to prepare a “box” (a database column) to receive the data.
2. Implementation: You must then send data to that box from your website using a tracking code.

Simply doing one without the other will result in failure. If you create it in the UI but never send data, the reports will be empty. If you send data with your code but have not created the dimension in the UI, Matomo will ignore the data.

Step 1: Create the Dimension in the Matomo UI

This is the non-technical part of the setup.

1. Log in to your Matomo instance with your Admin or Write-level account.
2. In the top right, click the Administration (cog icon).
3. In the left-hand navigation menu, go to the Measurables section (on some older versions, this may be called “Websites”).
4. Click on Custom Dimensions.
5. You will see two tables: “Visit Custom Dimensions” and “Action Custom Dimensions.” Below the correct table, click the “Create new custom dimension” link.
6. You will be presented with two fields:
   • Name: This is the human-readable name you will see in your Matomo reports. Make it clear and obvious, for example, “User Status” or “Article Category.”
   • Scope: This is the critical choice we discussed in the previous section. Click the dropdown and select “Visit” or “Action.”
7. Click the “Create” button.

Matomo will now reload the page. Your new custom dimension will be listed in the table. Look closely: it will have a new piece of information called the Dimension ID. It will look like dimension1 or dimension2.

This is the most important part of Step 1. The “Name” is for humans. The “ID” is for the code. You must note this ID. This ID (e.g., 1, 2, 3) is what you will use in your tracking code to tell Matomo which “box” to put the data in.

Step 2: Implement the Tracking Code

Now that Matomo has a “box” ready (e.g., dimension1), you need to go to your website and add the code to put data into that box. You have two primary methods for doing this.

Method 1: Direct Implementation (JavaScript Tracker)

This method involves editing your website’s code, usually the template or header, to add a line to your Matomo tracking snippet.

The command you need to use is _paq.push(['setCustomDimension', [Dimension_ID], '[Dimension_Value]']);

• [Dimension_ID]: This is the number you just noted from Step 1 (e.g., 1).
• [Dimension_Value]: This is the data you want to send (e.g., 'Premium-Member').

Example for a Visit Scope Custom Dimension (ID 1):

You want to track “User Status.” Your server-side code (like PHP or Python) would detect if the user is logged in, and then you would print this JavaScript snippet.

// This data would be dynamically set by your server
var userStatus = 'Premium-Member'; 

// Add this to your Matomo tracking code
_paq.push(['setCustomDimension', 1, userStatus]);

// This command is usually already on your page
_paq.push(['trackPageView']); 

For Visit scope custom dimensions, this command can be placed anywhere before the trackPageView call.

Example for an Action Scope Custom Dimension (ID 2):

This is more complex and requires careful timing. The setCustomDimension command must be placed before the trackPageView command it belongs to. This is because it is attaching data to that specific page view.

// On a blog post, this data would be set, maybe in the page's HTML or by your CMS
var pageAuthor = 'John-Doe';

// Set the Action scope custom dimension (ID 2)
_paq.push(['setCustomDimension', 2, pageAuthor]);

// NOW, track the page view. The dimension data will be sent with it.
_paq.push(['trackPageView']); 

If you place the setCustomDimension command after trackPageView, it will be too late. The page view will have already been tracked without your custom dimension data.

Method 2: Using Matomo Tag Manager (Recommended)

If you are using Matomo Tag Manager (MTM), the process is much cleaner and does not require you to edit your website’s code directly (assuming your MTM container is already installed). This method relies on a Data Layer.

A Data Layer is a small, invisible JavaScript object on your page that holds your business data. Your website’s backend would just populate this Data Layer.

Example Data Layer on a blog post:

<script>
  window.dataLayer = window.dataLayer || [];
  dataLayer.push({
    'pageAuthor': 'Jane-Smith',
    'pageCategory': 'Technology-Guides',
    'userStatus': 'Guest'
  });
</script>

Now, you can configure MTM to read this data.

1. In Matomo Tag Manager, go to the “Variables” tab. Create new variables of the type “Data Layer Variable” for pageAuthor, pageCategory, and userStatus.
2. Go to the “Tags” tab and open your main “Matomo Analytics” tag.
3. Inside the tag configuration, find the “Matomo Configuration Variable” and click to edit it.
4. Scroll down to the “Tracking Settings” section. You will see a setting for Custom Dimensions.
5. Click “Add new custom dimension.”
6. This is where you map everything:
   • Index: This is your Dimension ID from Step 1 (e.g., 1).
   • Value: This is where you insert your new MTM variable. Click the “Variable” icon and select {{userStatus}}.
7. Add another custom dimension:
   • Index: 2
   • Value: {{pageAuthor}}
8. Add another custom dimension:
   • Index: 3
   • Value: {{pageCategory}}
9. Save your variable, save your tag, and Publish your MTM container.

Now, your Matomo tag will automatically read the values from the Data Layer and send them to the correct custom dimension slots. This is the modern, flexible, and recommended way to manage custom dimensions.

Step 3: Verify Your Data

Do not assume it is working. You must verify that your new setup is collecting data correctly. A simple typo can stop all data from flowing.

• Method 1: Matomo Live Reports:The easiest way to check is to go to your Matomo dashboard and open the “Visitors” > “Visitor Log” or “Live!” report. Find your own visit (you can identify it by your IP address or location). Click the “View visitor profile” icon. In your visitor profile, you will see a table of your visit details. If your setup is correct, you will see your new custom dimensions listed with the values you sent.
• Method 2: Browser Developer Tools (Advanced):For real-time debugging, use your browser’s developer tools.
  1. Open your website.
  2. Press F12 to open “Developer Tools.”
  3. Go to the “Network” tab.
  4. In the filter box, type matomo.php or sendBeacon to find the tracking request.
  5. Refresh your page to trigger a new trackPageView.
  6. Click on the matomo.php request that appears in the list.
  7. Look at the “Headers” or “Payload” tab. You will see all the data being sent to Matomo. Scroll through the list of query parameters.
  8. If your setup is working, you will see your custom dimension data in the URL, for example: ...&dimension1=Premium-Member&dimension2=John-Doe&...

If you see these parameters, your implementation is a success. Matomo is receiving the data.

Advanced Techniques and Reporting

Setting up custom dimensions is only the first half of the equation. The second, more valuable half is using the data you now have. Once Matomo begins to process these new data points, your analytics capabilities expand significantly.

How to View Custom Dimension Reports

Once data has been successfully collected and processed for a day or two, Matomo will automatically create new reports for you. You do not need to build or configure anything new to see them.

Where to find them depends on the scope you chose:

• For Visit Scope Custom Dimensions:In the Matomo dashboard, navigate to the Visitors menu on the left. Inside this menu, you will find a new report matching the “Name” you gave your dimension (e.g., “User Status”).
• For Action Scope Custom Dimensions:Navigate to the Actions menu on the left. Inside this menu, you will find a new report for your dimension (e.g., “Page Author”).

When you open one of these new reports, you will see a standard Matomo data table. The first column will list all the values you have been sending (e.g., “Guest,” “Premium-Member,” “Free-Trial”). The subsequent columns will show all the standard metrics (Visits, Pageviews, Bounce Rate, Goal Conversion Rate, Revenue, etc.) for each of those values.

This is the payoff. You can now definitively say, “Our ‘Premium-Member’ segment has a 15% conversion rate, while our ‘Guest’ segment only has a 1.2% conversion rate.” This is actionable, high-value data that custom dimensions make possible.

Automatic Value Extraction (Action Scope Only)

This is a powerful, code-free technique for populating Action scope custom dimensions. In some cases, the data you want to track is already present in your Page URL, Page Title, or a URL Query Parameter. Matomo can “extract” this value automatically, without you needing to use setCustomDimension in your code.

Use Case:

Imagine your website’s help section has URLs like this:

https://example.com/help/general/getting-started

https://example.com/help/billing/update-card

https://example.com/help/api/authentication

You want to track “Help-Section-Category” (e.g., “general,” “billing,” “api”) as a custom dimension.

How to set it up:

1. Go to Administration > Custom Dimensions and create a new Action Scope custom dimension named “Help Category.” Note its ID (e.g., dimension4).
2. In the table, click “Edit” on the “Help Category” dimension.
3. You will see a setting called Extraction. Here, you can define a rule.
4. Set the dropdown to Extract value from Page URL.
5. In the Pattern box, you must enter a Regular Expression (Regex). A Regex is a special string for describing a search pattern. For this example, you would enter: \/help\/([a-zA-Z0-9\-]+)\/
6. The parentheses () define the part of the pattern to extract. This Regex tells Matomo: “Look for /help/, then extract the text string after it until you hit the next /.”
7. Save the dimension.

Now, you are done. You do not need to add any tracking code. When a user loads a page with /help/billing/ in the URL, Matomo will automatically see the URL, apply your Regex, extract the value “billing,” and populate your “Help Category” custom dimension with that value. This is an elegant and efficient way to manage content-based custom dimensions.

Advanced Use Case: Combining User ID with Custom Dimensions

This is one of the most strategic applications of custom dimensions. The Matomo “User ID” feature allows you to track a single user across multiple devices (e.g., their phone and their desktop) by assigning them a stable, anonymous ID (like a hashed email address or database ID) using the setUserId command.

The User ID feature by itself is powerful. But it only tells you who the user is. It doesn’t tell you what type of user they are.

By combining setUserId with a Visit Scope custom dimension, you can permanently enrich that user’s profile.

When a user logs in, you would send both commands:

// 1. Identify the unique user
_paq.push(['setUserId', 'USER_98765_HASH']);

// 2. Classify that user with a Visit scope custom dimension (e.g., ID 1)
_paq.push(['setCustomDimension', 1, 'Enterprise-Client']);

// 3. Track the action
_paq.push(['trackPageView']);

The Payoff: You can now use Matomo’s Custom Reports feature (a separate plugin or Cloud feature) to build reports that are not possible with default analytics. You can create a new report where the primary dimension is “User ID” and the secondary dimension is your new “Enterprise-Client” custom dimension. This allows you to analyze individual user journeys grouped by their subscription level, client type, or any other business logic you send. This moves your analytics from simple aggregation to true, user-centric analysis. These reports allow you to segment your entire Ecommerce or Goal funnel by the custom dimensions you have created.

Conclusion: From Data Collection to Actionable Insight

The proper implementation of custom dimensions is a fundamental turning point in the maturity of your analytics strategy. It is the mechanism that allows you to stop using an off-the-shelf tool and start building a data platform that is perfectly tailored to your organization’s unique structure.

Summary of Key Takeaways

To ensure your implementation is successful, remember these three core principles:

1. Use Custom Dimensions, Not Variables: Custom Variables are deprecated. All new implementations must use the modern, faster, and more powerful custom dimensions feature.
2. Scope is the Most Important Choice: Your entire setup depends on making the correct decision between “Visit Scope” (for user/session attributes) and “Action Scope” (for page/event attributes). A mistake here will invalidate your data.
3. It is a Two-Step Process: You must first create the dimension in the Matomo Admin UI to get an ID. You must second implement the tracking code (e.g., setCustomDimension or via Matomo Tag Manager) to send data to that ID.

Default analytics tell you what happened on your site. The correct use of custom dimensions tells you why it happened and to whom. By enriching your data with business-critical context like user roles, content categories, and author performance, you transform Matomo. It evolves from a simple traffic counter into a precise, customized business analytics platform, enabling you to finally make strategic decisions with confidence.