Mastering GA4 Custom Dimensions: The Ultimate Guide

Note: Empower yourself and others by sharing this insightful article on LinkedIn or social media. Let’s build a well-informed community together. Need help? Reach out anytime. 


Google Analytics 4 (GA4) has revolutionized the way we analyze web and app data. One of the standout features is the ability to create custom dimensions. Custom dimensions in GA4 allow you to collect and analyze data that is not automatically tracked. This tutorial will provide a comprehensive guide to setting up and using custom dimensions in GA4, helping you to unlock deeper insights into your user behavior.

What are custom dimensions in GA4?

Custom dimensions in Google Analytics 4 (GA4) are user-defined attributes that provide a more granular level of data collection and analysis beyond the default metrics. These dimensions allow you to capture and report on specific data points that are relevant to your business, which are not automatically tracked by GA4. For example, you can create custom dimensions to track user preferences, membership levels, or custom actions on your site.

Why use custom dimensions?

Custom dimensions enhance your tracking capabilities by allowing you to:

  • Track specific user interactions and events that are not captured by default.
  • Segment your audience more precisely based on custom attributes.
  • Gain deeper insights into user behavior and improve your marketing strategies.

    Take for example an eCommerce site with user login functionality. Custom dimensions in GA4 can be incredibly useful for gaining detailed insights into user interactions and events. For instance, you can use event-scoped custom dimensions to track detailed actions like the location of the “Add to Cart” button click, helping to understand which page or section drives the most cart additions. User-scoped custom dimensions can capture user-specific data such as membership type (e.g., “Regular Member” vs. “VIP Member”), providing insights into how different user segments interact with your site. Item-scoped custom dimensions can track custom details about each product interaction, such as stock availability and product type, helping to manage inventory and understand product popularity.

Setting up custom dimensions

Before you start, ensure you have a GA4 property and a Google Tag Manager (GTM) setup to track custom parameters. Once you have it follow the steps below:

  • Open your GA4 property.
  • Navigate to the Admin section and select “Custom Definitions.”
  • Click “Create Custom Dimension.”
  • Enter the dimension name, scope, and description.
  • Save the custom dimension.

Configuring Event Parameters in GTM

Event parameters are the building blocks of custom dimensions If you don’t have a custom parameter being tracked, here’s how to create them:

  • Open GTM and create a new tag.
  • Select “GA4 Event” as the tag type.
  • Configure the event parameters you want to track.
  • Use Tag Assistant to test and validate your setup.

Creating Custom Dimensions in GA4

  • Step 1-In Admin, under Data display, click Custom definitions.
  • Step 2-Select the Custom dimensions tab
  • Step 3-Click Create custom dimensions.
  • Step 4-Complete the following fields

Setting Up Event-Scoped Custom Dimensions


  • Choose “Event” as the scope in step 4.
  • Define the dimension and save it.

Setting Up User-Scoped Custom Dimensions

  • Follow the same steps as above
  • Select “User” as the scope in step 4.
Setting Up Item-Scoped Custom Dimensions  
  • Follow the same steps as above
  • Select “Item” as the scope in step 4.

Understanding Scope in Custom Dimensions

The scope of a custom dimension in GA4 determines how data is collected and applied.

Event-Scoped Dimensions:These are tied to specific actions, capturing data for each occurrence of an event like button clicks or form submissions. For example, tracking the location of an “Add to Cart” button click helps optimize user interactions.

User-Scoped Dimensions: These aggregate data across all user interactions, providing a comprehensive view of user behavior over multiple sessions. For instance, capturing a user’s membership type (e.g., “Regular Member” vs. “VIP Member”) aids in segmenting and targeting users more effectively.

Item-Scoped Dimensions: These are tied to individual items within an event, such as products in a purchase. They capture details like product type or stock availability, enabling detailed analysis of product performance and inventory management. For example, tracking stock availability for each product helps manage inventory and understand product popularity.

Best Practices for Naming and Descriptions

Match GTM Parameters: Name custom dimensions to reflect GTM event parameters, like button_click_location, for consistency.

Be Descriptive: Use clear, specific names that describe what the dimension measures, such as Button_Click_Location instead of Button.

Include Scope: Indicate the scope in the name, like User_Membership_Type for user-scoped dimensions.

Standard Naming Conventions: Use consistent naming conventions (e.g., underscores, capitalization) across all dimensions.

Clear Descriptions: Provide detailed descriptions to explain the purpose and usage of each custom dimension

Importance of Consistency and Clarity

Consistency and clarity ensure accurate data collection, ease of analysis, effective team collaboration, and scalability. Clear and standardized naming conventions help maintain data quality and make it easier for everyone to understand and use the data effectively.

Common Pitfalls and How to Avoid Them

  • Don’t create a custom item-scoped parameter if a predefined dimension already exists.
  • Make sure the custom parameter is being collected. For example, you can select an event in the Event count by Event name card in the Realtime report.
  • When working with custom dimensions in GA4, it’s essential to be aware of quota limitations. Free GA4 accounts allow up to 50 custom dimensions per property, while GA4 360 accounts offer up to 125.

    Here’s a breakdown of the quotas:

To manage these quotas effectively, ensure that custom dimensions are as broadly applicable as possible.
Another common pitfall is dealing with data accuracy and completeness. Avoid registering custom dimensions for parameters with high cardinality, as this can lead to data inaccuracies. Instead, focus on dimensions that provide widespread and valuable insights across your data set.

Editing and Archiving Custom Dimensions

If you reach the limit on custom dimensions or metrics, you can free up space by archiving unused ones. Archiving affects any audiences, explorations, segments, or custom reports using the archived dimension or metric. This action is irreversible and the corresponding data cannot be restored. To do that –
1.In Admin, under Data display, click “Custom definitions.”
2.In the row for the custom dimension or metric, click More > Archive.
3.Review the entities that use the custom dimension or metric.
4.Click Archive.

Impacts of archiving a custom dimension:

Archiving a custom dimension or metric used in an audience invalidates the audience, stopping new user data accumulation. Historical data is preserved, but no new data is generated. Invalid audiences cannot be exported to other products.

Warning icons appear in Explorations for segments using archived custom dimensions or metrics. These segments become invalid and won’t load. Removing the archived definition allows the segment to load.
Archiving custom dimensions or metrics makes reports using them invalid until they are removed.


Editors or administrators can follow these steps:
1.Click “Customize report” on the top right.
2.Open the dimension or metric picker in the Report data section.
3.Remove the archived custom dimension or metric from the report.

Using Custom Dimensions in Reports

If you are an editor or administrator, you can add the custom dimension to any report after 24-48 hours from when the custom data was sent and the custom dimension was created.

To add the custom dimension to a free-form exploration:
1.In Google Analytics, click Explore on the left.
2.Create or open a free-form exploration.
3.In the Variables column on the left, click + next to Dimensions.
4.Click the Custom tab at the top.
5.Select the custom dimension.
6.Click Import.
7.Drag the dimension from the Variables column.
8.Drop the dimension into Rows or Columns in the Settings column.

Example of custom reports and analysis.

Advanced Tips for Custom Dimensions

Integrating with BigQuery for advanced analysis.

Custom dimensions in GA4, whether event-scoped, user-scoped, or item-scoped, can be exported to BigQuery for advanced analysis. Here’s how each type integrates with BigQuery:

Event-Scoped Custom Dimensions:
Event-scoped dimensions are parameters of an event type. In the BigQuery export table, these are nested within the row for each event. For instance, if you have custom dimensions like published_date and page_id for a page_view event, you can find them in the event_params array.

To analyze these:
1.Locate the page_view event in the event_name column.
2.In the row for the page_view event, find event_params.key and event_params.value.string_value to see your custom dimensions.
3.Unnest these arrays to access and analyze the data.

User-Scoped Custom Dimensions:
User-scoped dimensions apply to user attributes and persist across sessions. In BigQuery, these dimensions are found in the user_properties array. To analyze user-scoped dimensions:

1.Identify the relevant user property in the user_properties.key column.
2.Access the values in user_properties.value.string_value.
3.Unnest the array to work with the data.

Item-Scoped Custom Dimensions:
Item-scoped dimensions are tied to specific items within an event, such as products in a purchase. These dimensions are included in the items array for each event. To analyze item-scoped dimensions:

1.Find the relevant event containing the items array.
2.Look for custom parameters within the items array in columns like items.item_name and items.item_category.
3.Unnest the array to analyze the custom parameters for each item.

Here’s a generic example of how you can query for custom dimensions:


Q: What is a dimension?
A: A dimension is an attribute of your data that describes it, usually in text form as opposed to numbers. Dimensions help you categorize and analyze data effectively.

Q: Can I delete a custom dimension?
A: No, GA4 does not allow you to delete custom dimensions. However, you can archive them, which stops new data from being collected for that dimension.

Q: What happens if I archive a custom dimension?
A: Archiving a custom dimension affects any audiences, explorations, segments, or custom reports that use it. The dimension will no longer collect new data, and any reports or segments using it will need to be updated to remove the archived dimension.

Q: How can I manage my custom dimension quota?
A: To manage your quota, ensure that custom dimensions are broadly applicable and avoid creating dimensions for parameters with high cardinality. Regularly review and archive unused custom dimensions to free up space for new ones.

Q: What is the value limit for custom dimensions in GA4?
A: The length of a custom dimension name is limited to 24 characters, and the length of its value is limited to 36 characters. For event-level dimensions, you can create up to 50 of them, and their length must fit within 100 characters when sent as parameters to GA4.

About Author

Prateek is an analytics consultant at Datavinci by day and a storyteller by night. With expertise in the GMP stack, he believes that data is the ultimate narrator - well, at least until the numbers stop adding up. He enjoys untangling complex concepts and making them as straightforward as his love for a good plot twist. When he's not buried in data, he's lost in a good book - mostly fiction, to balance the analytical mind.

Share This Article:
Table of content

Related Stories

Frustrated by 'Not Set' appearing in your Google Analytics reports? Discover the common causes behind this...
Unlock the full potential of your Calendly integration with enhanced conversion tracking using Google Tag Manager....
Unlock the full potential of your website with our step-by-step guide on adding Facebook Pixel using...
Learn how to efficiently store data in local storage using Google Tag Manager with our comprehensive...