This article is about Google Analytics 4 properties. Refer to the Universal Analytics section if you're still using a Universal Analytics property, which will stop processing data on July 1, 2023 (July 1, 2024 for Analytics 360 properties).

[GA4] Custom dimensions and metrics

Create new dimensions and metrics from event parameters
If you haven't customized your data collection code, you probably do not need to read this article or use custom dimensions and metrics.

Google Analytics automatically provides many dimensions and metrics. However, if you have customized your data collection code to collect non-standard event parameters, you'll need to create custom dimensions and/or custom metrics in order to make use of these event parameters. For example, let's say that you send the following event each time someone reads an article on your site. In this event, you collect the author name, the article title, and the number of pages in the article.

gtag('event','read_article', {
    "author":"Bill Q",
    "title":"How to Build a Backpack",

You can create an Author dimension that gets its values from the author parameter and an Article_Length metric that gets its value from the number_of_pages parameter.

You don't need to set up custom dimensions and metrics for data collected through automatically collected eventsenhanced measurement, and recommended events

Event and user scope

A custom dimension has either an event scope or user scope.

  • Event scope: In the example above, you would create the Author dimension to have an event scope.
  • User scope: Create user-scoped custom dimensions to identify static or slowly changing attributes of your users, such as "spender=true", "profession=engineer", or "favorite_team=Real Madrid".

A custom metric always has an event scope.


If you hit any of these limits and need to create more custom dimensions or metrics, archive the ones you don't use:

Item Standard property limits Analytics 360 property limits
Event-scoped custom dimensions 50 125
User-scoped custom dimensions 25 100
All custom metrics 50 125

To see the number of custom dimensions and metrics you've created:

  1. On the left, click Configure > Custom definitions.
  2. On the top right, click Quota information.

Certain custom dimensions aren't available in your reports when combined with demographic information. You may experience thresholding or incompatibility constraints when requesting custom dimensions with demographic data.

Custom dimensions and metrics best practices

Before you create custom dimensions and metrics, use the dimensions and metrics that Analytics populates by default.

If you have a standard Google Analytics 4 property, avoid creating unnecessary high-cardinality custom dimensions. High-cardinality dimensions may negatively impact your reports and cause data to aggregate under the (other) row.

Below are a few examples that lead to high-cardinality dimensions and are either not 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 user ID use cases, without registering User ID as a Custom Dimension.
  • Using a custom dimension to send unique IDs per session, like a Session ID
  • Sending a timestamp as a custom dimension

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 be using up one of your custom dimension quota. Ensure you are familiar with the predefined dimension options before using your custom dimensions in GA4.

Create custom dimensions

You need the Editor role to create custom dimensions.

  1. On the left, click Configure > Custom definitions.
  2. Click Create custom dimensions.
  3. Enter a name for the custom dimension.
    You can't use hyphens in the name, but you can use underscores and spaces instead.
  4. Select a scope for the custom dimension. Learn more
  5. Enter a description for your custom dimension.
  6. Select an event parameter or user property from the list or enter the name of an event parameter or user property you'll collect in the future.
  7. Click Save.

You will see a value of (not set) for a custom dimension in the first 48 hours.

Create custom metrics

You need the Editor role to create custom metrics.

  1. On the left, click Configure > Custom definitions.
  2. Click Create custom metrics.
  3. Enter a name for the custom metric.
    You can't use hyphens in the name, but you can use underscores and spaces instead.
  4. Enter a description for your custom dimension.
  5. Select an event parameter from the list or enter the name of an event parameter you'll collect in the future.
  6. Choose a unit of measurement from the drop-down.
    When you select Currency as the unit of measurement, you must also identify the custom metric as a cost and/or revenue metric under Data type. When you identify the custom metric as a cost and/or revenue metric, you can restrict access to it when you configure user roles that restrict access to cost and/or revenue metrics.
  7. Click Save.

Custom metrics can take 24-48 hours to populate with data.

Edit custom dimensions & metrics

You need the Editor role to edit custom dimensions or metrics.

  1. On the left, click Configure > Custom definitions.
  2. In the row for the dimension or metric, click More > Edit.
  3. Make the changes you want, then click Save.

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?

Need more help?

Sign in for additional support options to quickly solve your issue

Clear search
Close search
Google apps
Main menu
Search Help Center