Websites generate an endless stream of behaviour signals each day. Page views, traffic sources and bounce rates paint part of the picture, yet the deeper story often remains hidden. Campaigns may succeed with one group but fall flat with another, and content that drives strong engagement in one segment may barely register in the next.
This gap between what happened and why it happened is a common challenge in analytics. Standard dashboards surface general patterns but struggle to explain their context.
Custom dimensions offer a way to capture that missing context by attaching meaningful attributes to visits and actions. Details, such as user roles, content categories or subscription tiers, can transform raw activity into insight.
This article explores what custom dimensions are, how they work in Matomo and how to set them up for clearer, more relevant reporting.
What are custom dimensions?
Custom dimensions are extra pieces of information attached to visits or actions in an analytics tool. Instead of relying only on default fields, such as page URL or traffic source, an analyst can store tailored attributes that matter to the business, then use them in reports for deeper insight.
Each custom dimension holds a name and a value. During tracking, the value is sent with the hit, and Matomo stores it alongside standard metrics. When reports run, Matomo groups and filters data by these values, which keeps the analysis accurate and consistent.
For example, a “subscription tier” custom dimension can record whether a visitor is on a Free, Pro or Enterprise plan. Another might capture “Content type,” such as article, video or product page.
Custom dimensions can be set up to avoid personal data, which helps teams measure behaviour without tracking names or contact details. They also give analysts more say in how results are grouped in reports.
Common use cases
Custom dimensions are most useful when they add context that standard metrics miss. The examples below show how a few extra fields can turn log data into clear, practical findings.
Content performance tracking
Editors can tag visits with content author, category or content type. Reports then reveal which authors keep visitors engaged, which categories attract new audiences and whether articles, videos or product pages drive the most conversions.
User segmentation
Marketers often track subscription tier, user type or acquisition channel as custom dimensions. A tier such as Free, Pro or Enterprise can be followed through funnels to compare feature usage, upgrade rates and campaign performance with clear, transparent splits.
Ecommerce insights
Stores can attach product attributes, such as brand or collection, along with the customer lifetime value band. That makes it easier to compare groups that spend more or stay longer, without storing personal data.
Technical tracking
Teams can record a page load time band or an error type. Lining those values up against clicks and conversions shows where slow pages or repeating errors cause visitors to drop off.
Implementing and managing custom dimensions
Implementing custom dimensions in Matomo follows two stages: define the dimension, then send values with each relevant hit. A little planning at this point protects accuracy, performance and privacy later.
Step 1: Plan and create the dimension
Before creating a new dimension, teams decide whether it should describe an entire visit (visit-scoped) or a single interaction, such as a page view or event (action-scoped).
In Matomo, administrators click:
- The Administration page (cog icon)
- Measurables or Websites (depending on setup) in the left-side menu
- Custom Dimensions
They can then add a name, choose the scope and set the dimension as active.
Because each site has a limited number of slots per scope and dimensions usually can’t be deleted, only deactivated, most teams reserve them for stable concepts, such as subscription tier or content group, rather than volatile labels.
Step 2: Track values from the site or app
For sites that use the JavaScript tracker, custom dimensions are attached to hits through the _paq queue.
This simple example records a visitor’s plan:
| _paq.push([‘setCustomDimension’, 2, ‘Pro’]); |
This call runs before the relevant trackPageView or event, and Matomo stores the value alongside the standard metrics for that visit or action.
Matomo Tag Manager offers another route and keeps tracking logic in one place. A variable first captures the value, like a data layer field that holds userRole. In the Matomo Configuration Variable, the Custom Dimensions section maps a dimension index to that variable. When a tag that uses this configuration fires, it sends the custom dimension value with the hit. In preview mode, teams can check the container and see those values in the request before publishing any changes.
Server-side systems, background jobs or mobile apps that call the HTTP Tracking API add custom dimensions with dimension{id} parameters, such as dimension2=Enterprise. Separate ranges support visit and action scopes, which help keep imports structured and efficient.
Step 3: Maintain and validate
After tracking is live, teams should watch reports and logs for empty rows or odd values.
Action dimensions can also take values from URLs or page titles through extraction rules. That approach cuts down on code edits and makes it clear where each value comes from.
Periodic reviews of active dimensions, along with consent and data minimisation settings, help ensure the implementation remains accurate, privacy-friendly and easy to extend.
How custom dimensions affect analytics and reporting
Once custom dimensions begin collecting data, they become part of Matomo’s standard reporting flow.
Each dimension appears in dedicated reports where metrics are grouped by the stored values. It keeps analysis consistent and makes it clear how attributes (like subscription tier or content type) relate to behaviour and results.
Matomo processes visit-scoped and action-scoped dimensions differently:
- Visit-level dimensions describe the whole session, so reports summarise complete visits and conversions by each value.
- Action-level dimensions attach to individual events, page views or downloads. In these reports, a single visit can contribute multiple rows, which helps expose detailed patterns, like which content category generated the most downloads or form submissions.
Custom dimensions can also feed Custom Reports. Analysts can add a dimension as a row or column, then filter by action type to focus on events, downloads or other specific interactions. This level of control, combined with clear scopes, supports accurate reporting and efficient workflows without obscuring how Matomo stores and processes the underlying data.
Privacy and compliance considerations
Custom dimensions can touch personal data, depending on implementation, so they form an important part of privacy and compliance work.
Under GDPR and similar laws, any field that can identify or single out a person needs a lawful basis, a clear purpose and suitable safeguards. In practice, this means planning dimensions with legal and privacy teams, as well as analysts.
Data minimisation, careful consent management and anonymisation are at the core of a privacy-forward and compliant implementation.
For custom dimensions, that often means recording stable, non-identifying values, such as subscription tier or an internal segment label, instead of names or email addresses. It also means linking records with a pseudonymous ID.
Data minimisation keeps each dimension tied to a single purpose. Retention rules and deletion processes then clear out values once they are no longer needed. Anonymisation and aggregation features in Matomo, including IP masking and optional cookieless tracking, help reduce risk further when combined with explicit consent where required.
Planned this way, custom dimensions support accurate analysis while maintaining transparency, user control and respect for local privacy requirements.
Advanced tips and best practices
Reserve slots for stable attributes
Custom dimension slots are limited and difficult to restructure later, so teams should stick to stable ideas and stay away from ultra-granular values that will bloat tables.
Planning ahead of time and consulting the Matomo Measurement Plan can prevent performance issues or dimension limit frustrations down the road.
Avoid high-cardinality values
High-cardinality dimensions, meaning those that have a large or infinite number of unique values, increase archive time and slow down reporting. Teams should avoid using dynamic values for their dimensions, like time stamps or full URLs with parameters.
Keep names simple and consistent
Naming matters. Simple labels such as “Subscription tier” or “Content category” make reports easier to scan and make future changes less painful.
A shared naming convention for events, custom dimensions and variables helps everyone understand what each field stores and how it shows up in dashboards and exports.
Troubleshooting common issues
Data not appearing in reports
The most common cause of missing data is scope or timing. The dimension must be:
- Active
- Attached to the correct site
- Sent before trackPageView or the relevant event
Reports only show data for the selected date range, so very recent hits may appear first in real-time or visit logs before they reach aggregated reports.
“undefined” or “Value not defined” dimension values
Reports may display “undefined” or “Value not defined” as a dimension value.
This has two causes:
- The tracker tried to use a variable that wasn’t defined when setCustomDimension was called, so it’s received as “undefined”
- The dimension was sent with an empty string, so it displays as “Value not defined”
To fix this, teams should set the dimension before the pageview or event is tracked and confirm that the variable returns a real value (unless intentionally left empty).
Inconsistent formatting
Inconsistent formats fragment results. For example, recording “pro”, “Pro” and “PRO” as separate values inflates the number of rows and makes comparisons harder.
Shared naming conventions and validation on the data layer keep values accurate and readable.
Implementation validation
Tag Manager preview mode and browser Network tabs can confirm that dimension{id} is included in a tracking request. Teams can verify values in the Visitor Log before relying on aggregated reports.
Teams should also review dimension values to make sure no personal data is sent and the consent setup blocks tracking where required.
Using custom dimensions in Matomo
Custom dimensions fit neatly into Matomo’s privacy-first approach. The platform combines 100% data ownership with options such as IP anonymisation, cookieless tracking and no data sampling, so added context does not come at the expense of privacy or accuracy.
Matomo treats custom dimensions as first-class fields in many features. They appear in dedicated reports, can act as rows or columns in Custom Reports and can filter or group Goals, Funnels and E-commerce reports. A “Subscription tier” dimension, for example, can break down goal completions by Free, Pro and Enterprise across landing pages, events and revenue, which gives teams a clear view of how each tier behaves.
Business Matomo Cloud plans come with 15 visit-scope and 15 action-scope dimensions, but Enterprise’s total amount is customisable. On Matomo On-Premise, administrators can extend the default five per scope to around 50 per scope through a console command with SSH access.
Custom dimensions as a foundation for trusted analytics
Custom dimensions close the gap between raw metrics and meaningful insight by restoring context to every visit and action.
Instead of isolated page views and bounce rates, teams gain a structured view of how real audiences behave across content, products and technical experiences.
In Matomo, this richer picture rests on a trusted base: accurate data with no sampling, an open-source platform used by more than 1 million websites and features that can be configured for GDPR compliance.
For organisations that value privacy and control, Matomo’s custom dimensions provide a practical path to clearer, more confident decisions.
Download Matomo and run it for free on your own server or start your free Matomo Cloud trial today — no credit card required.
FAQ
What is a custom dimension?
A custom dimension is a field that stores extra context for a visit or action, such as user role or content category. It appears in dedicated Matomo reports.
When should I use custom dimensions vs. custom variables?
Custom dimensions are the modern way to track extra metadata in Matomo. Custom variables are deprecated and mainly kept for legacy installations.
What’s the maximum number of custom dimensions allowed in Matomo?
Matomo Cloud Business Plan supports 15 custom dimensions per scope (visit and action), so 30 in total. The Enterprise plan has customisable limits.
On-Premise starts at 5 per scope and can be extended to at least 50 per scope using console tools with SSH access.
Can you add custom dimensions retroactively in Matomo?
Custom dimensions record values from the time tracking is implemented. Earlier visits without that value remain empty in reports.
How do custom dimensions differ from segments in Matomo?
A custom dimension adds a new field to the dataset, like a membership tier. A segment filters existing data, such as visits from a specific region.
Are Matomo custom dimensions GDPR-compliant?
Custom dimensions in Matomo can be made GDPR-compliant when configured and governed correctly, following consent, data minimisation, limited retention and anonymisation of personal data where possible. You can learn more in our handy GDPR guide.
Can I use custom dimensions in Matomo’s mobile app analytics?
Yes. Matomo’s mobile SDKs for Android and iOS support tracking custom dimensions alongside events, screens and ecommerce actions.
