Dimensions and metrics

[GA4] About custom dimensions and metrics

Analyze and advertise using the custom data from your website or app

A custom dimension or metric in Google Analytics enables you to analyze and advertise using the custom data you've gathered from your website or app. A custom dimension or metric goes beyond the standard data automatically collected and surfaced by Google Analytics, allowing for more detailed and relevant analysis.

Custom Dimensions and Metrics in Google Analytics

How it works

Events measure what users do on your website or app, like clicking a link or watching a video. Event parameters provide more details about these actions, like which link was clicked or how much of the video a user watched. User properties tell you more about the users themselves, like their age or location.

Google Analytics automatically collects some data after you set up Analytics by sending automatically collected events and predefined user properties. You can find a list of automatically collected events and their event parameters in Google Analytics event parameters.

After you collect this extra information on your website and/or app, you can set up custom dimensions (for descriptive data) and custom metrics (for numerical data) to organize and analyze the data in reports. Custom dimensions and metrics also let you use that data for advertising and remarketing.

A custom icon that illustrates a user clicking a “add to basket” button on a website.


A custom icon that illustrates a website on a laptop and a mobile phone with the Google Tag.


A custom icon that illustrates adding custom dimensions by selecting checkboxes.


A custom icon that illustrates a dashboard with a 2-line chart and a pie chart.


You add an event parameter or user property to your website or mobile app code

A user visits your website or app and the custom data is sent to Google Analytics

You create a custom dimension or metric so you can analyze the data from the event parameter or user property

After 24-48 hours, you can start to report on and advertise with the custom dimension or metric

Types of custom dimensions and metrics

You can create a few different types of custom dimensions and metrics depending on the information you want to report on and advertise with:

Custom dimensions

  • User-scoped custom dimensions enable you to report on custom user properties. When you add a custom user property into your website or app code, these custom dimensions unlock the ability to dissect and understand the user-specific data.
  • Event-scoped custom dimensions enable you to report on custom event parameters, which measure details about user actions captured through an event. Whether you're identifying clicked links or video engagement, adding a custom event parameter to your recommended events or custom events allows for in-depth analysis of these interactions.
  • Item-scoped custom dimensions are useful for ecommerce websites and mobile apps. These custom dimensions enable you to analyze custom data like item color or item size within the items array of an ecommerce event like 'purchase' or 'add_to_cart.'

Custom metrics

  • Custom metrics enable you to analyze numerical values from event parameters. If an event parameter measures the quantity or frequency of an action, custom metrics transform those figures into actionable insights. For categorical data, however, such as what text was clicked or which page was viewed, it's more appropriate to use an event-scoped custom dimension.
  • Calculated metrics enable you to combine one or more existing metrics and/or custom metrics to produce a new and potentially more valuable metric.


The following table shows how many custom dimensions and metrics you can create for standard and 360 properties:

Types of custom dimension or metric Standard property limits 360 property limits
User-scoped custom dimensions 25 100
Event-scoped custom dimensions 50 125
Item-scoped custom dimensions 10 25
Custom metrics 50 125
Calculated metrics 5 50


You can see when you're close to hitting the maximum number of custom dimensions or metrics on the Custom definitions page within Admin. To see the number of custom dimensions and metrics you've created so far, click Quota information on the top right.

Best practices

Before you create custom dimensions and metrics, use the predefined dimensions and metrics whenever possible.

If you have a standard property, do not create unnecessary high-cardinality custom dimensions. High-cardinality dimensions may negatively impact your reports and explorations, and cause data to be condensed under the (other) row.


The following are examples of high-cardinality dimensions that aren't allowed or should be avoided:

  • Using a custom dimension for a unique ID per user; instead, use the User-ID feature
    • Learn more about how to meet your use cases without creating a custom dimension for a user ID
  • Using a custom dimension to send unique IDs per session, like a Session ID
  • Sending a timestamp as a custom dimension

Note: When sending data to Google Analytics, any value in a custom dimension that resembles a number will be treated as a number, even if it was originally formatted as text.


  • If you send "9343.324234" (as text), GA4 will interpret it as the number 9343.32.
  • If you send "94E40" (as text), GA4 will interpret it as the number 9.4e+41 (scientific notation).

Lastly, registering a custom dimension for a parameter that is already a predefined dimension, such as the page and screen dimensions, or transaction ID, is not a best practice. It will not affect cardinality, but it will use one of your custom dimension quota.

Deprecation of custom-parameter reporting

With event-scoped custom dimensions and metrics, parameters are identified for property-wide dimensions and metrics, allowing you to create a single dimension or metric based on a parameter and report on it for as many events as you wish. Previously with custom-parameter reporting, parameters were identified for individual events. Consequently, if you wanted to report on the same parameter for five different events, you had to use five of your quota of 100 custom dimensions and metrics.

With the deprecation of custom-parameter reporting, Analytics has preserved historical event-scoped aggregates, and new aggregates seamlessly extend that historical data. In cases where a parameter was registered for multiple events, Analytics disambiguates between them by assigning a dimension/metric name that includes the currently assigned event name (e.g., “custom_dimension_name [event_name]”).

As a best practice, you should remove duplicate custom dimensions and metrics that were registered across multiple events to help preserve your quota.

User-scoped custom dimensions eliminate the need for you to think about "slots". User properties become aliases for user-scoped custom dimension slots, allowing developers to focus on tracking meaningfully named data points without having to associate each data point with an arbitrary slot number.

Was this helpful?

How can we improve it?
Clear search
Close search
Google apps
Main menu