GA4 Custom Dimensions: The Complete Guide.

Custom dimensions are how you extend GA4 beyond its default schema. They let you attach your own data — content categories, user types, subscription tiers, A/B test variants, and more — to events and users, making your reports far more useful. But GA4's custom dimension model is fundamentally different from Universal Analytics, and the old mental models will get you into trouble if you don't understand the new rules.

This complete guide covers everything analytics teams need to know about GA4 custom dimensions: how they work under the hood, the critical registration limits, scope differences, naming conventions, and the most common mistakes we see in audits.

What Are GA4 Custom Dimensions?

How Custom Dimensions Work in GA4

In Universal Analytics, custom dimensions were a separate concept from hit-level data. In GA4, the architecture is completely different: everything is an event parameter. There's no separate "dimension" data type. When you push dataLayer.push({ event: 'purchase', payment_method: 'credit_card' }), the payment_method is an event parameter. (For the naming and structuring rules that apply to the event itself, see our guide to GA4 custom events.)

A "custom dimension" in GA4 is simply an event parameter that you've registered in the GA4 admin panel so it becomes available in standard reports and explorations. Without registration, the parameter is still collected and stored (it appears in BigQuery exports and DebugView), but it's invisible in the GA4 reporting interface.

This subtle but critical distinction means: you can send unlimited event parameters, but only a limited number can be registered as custom dimensions for use in reports.

Event-Scoped vs User-Scoped vs Session-Scoped

Understanding Scope

Scope determines how a custom dimension is associated with user activity. Choosing the wrong scope is one of the most common sources of errors in GA4 implementations:

• Event-scoped dimensions attach data to individual events. Use these for data that changes from event to event: content_group, payment_method, button_text, search_query, error_type. Each event carries its own value for the dimension.
• User-scoped dimensions attach data to the user profile and persist across all future events until overwritten. Use these for stable user attributes: subscription_tier, customer_type, company_size, signup_source. Once set, this value applies to every subsequent event from that user.
• Session-scoped dimensions (available in GA4 360) attach data to a session and apply to all events within that session. Use these for session-level context: traffic_source_detail, landing_page_type, or ab_test_variant when the variant is assigned per session rather than per user.

A common mistake is using event-scoped dimensions for data that should be user-scoped. For example, if you set subscription_tier: 'premium' as an event parameter only on the login event, it won't appear on subsequent page views, purchases, or other events from the same user. User-scoped dimensions solve this by persisting the value across the entire session and future sessions.

Registration Limits

GA4 imposes strict limits on the number of custom dimensions you can register:

• Event-scoped custom dimensions: 50 (standard properties) or 125 (GA4 360)
• Event-scoped custom metrics: 50 (standard) or 125 (360)
• User-scoped custom dimensions: 25 (standard) or 100 (360)
• Item-scoped custom dimensions (ecommerce): 10 (standard) or 25 (360)

These limits are significantly lower than the effective limits in Universal Analytics, where you could have 20 custom dimensions per hit. In GA4, you need to be much more strategic about what you register.

Important nuance: deleting a custom dimension doesn't free up a slot immediately. De-registered dimensions enter an "archived" state, and the slot becomes available again after 48 hours. Plan your dimension usage carefully rather than constantly adding and removing.

How to Register a Custom Dimension in GA4

1. Go to Admin → Custom Definitions → Custom Dimensions.
2. Click Create Custom Dimension.
3. Enter a Dimension Name (this is the display name in reports, e.g., "Content Group").
4. Select the Scope: Event or User.
5. Enter the Event Parameter or User Property name (this must exactly match the parameter name in your dataLayer/GTM, e.g., content_group).
6. Optionally add a Description for documentation purposes.
7. Click Save.

After registration, the dimension begins appearing in reports and explorations. Registration is not retroactive — historical data before registration won't include the dimension in reports (though it's still in BigQuery if you have export enabled).

Implementation

Sending Event-Scoped Parameters

To send an event-scoped custom dimension, include the parameter in the event call:

dataLayer.push({
  event: 'page_view',
  content_group: 'Product Reviews',
  author_name: 'Jane Smith'
});

Or via gtag directly:

gtag('event', 'page_view', {
  content_group: 'Product Reviews',
  author_name: 'Jane Smith'
});

Setting User Properties

User-scoped dimensions are set via user properties, not event parameters:

gtag('set', 'user_properties', {
  subscription_tier: 'premium',
  customer_type: 'returning'
});

In GTM, use the "Set User Properties" tag type to persist user attributes. Once set, the value applies to all subsequent events from that user in the same and future sessions until you overwrite it with a new value.

Advanced: Item-Scoped Dimensions for Ecommerce

In addition to event-scoped and user-scoped dimensions, GA4 supports item-scoped custom dimensions (also known as custom item parameters). These attach data to individual items within the items array of ecommerce events. You can register up to 10 custom item dimensions on standard properties.

Common item-scoped dimensions include item_color, item_size, item_rating, or item_stock_status. These allow you to break down ecommerce performance by product attributes that aren't part of the standard GA4 ecommerce schema.

Common Mistakes

The 4 Most Common Custom Dimension Errors

1. Not registering parameters:

   This is the most frequent issue. Teams send event parameters like content_group, author_name, or product_category through GTM, but never register them in the GA4 admin. The data is collected — you can see it in DebugView and BigQuery — but it's completely invisible in standard reports and explorations. Always verify that every event parameter you want to report on is registered as a custom dimension.

2. Wrong scope:

   Using event-scoped when it should be user-scoped (or vice versa). Classic example: sending membership_level as an event parameter on the login event. This means the data only exists on that one event, not on subsequent page views or conversions. It should be a user-scoped dimension set via gtag('set', 'user_properties', { membership_level: 'gold' }).

3. Hitting the 50-slot limit:

   Teams register every parameter they've ever sent without pruning unused dimensions. Before registering a new dimension, audit your existing ones: Are they all still being sent? Are they all used in reports? Archive any that haven't received data in the last 90 days to keep your slots available for dimensions that matter.

4. PII in dimension values:

   Accidentally passing email addresses, phone numbers, full names, or other personally identifiable information as custom dimension values. This violates Google's Terms of Service and can result in your GA4 property being permanently deleted. Implement server-side sanitization or GTM variable transformations to hash or exclude PII before it reaches GA4.

Naming Conventions for Custom Dimensions

Consistent naming makes your dimensions discoverable and maintainable as your implementation grows:

• Use snake_case for parameter names: content_group, not contentGroup or Content Group.
• Use descriptive prefixes for categorization: page_ for page-level data, user_ for user attributes, product_ for e-commerce properties.
• Avoid generic names: category is ambiguous — use content_category or product_category instead.
• Don't use reserved parameter names: GA4 reserves certain names like page_title, page_location, screen_name, and others. Check Google's documentation for the full list.
• Keep names under 40 characters: shorter names are easier to work with in queries and reports.

Key Takeaways

• Custom dimensions in GA4 are registered event parameters — the data is collected whether or not you register them, but it's only visible in reports after registration.
• You have 50 event-scoped and 25 user-scoped dimension slots on standard properties — use them strategically and audit regularly.
• Choose the correct scope: event-scoped for data that varies per interaction, user-scoped for stable user attributes, session-scoped (360 only) for session-level context.
• Never put PII in dimension values — hash or exclude sensitive data before it reaches GA4.
• Enable BigQuery export as a safety net — all parameters (registered or not) are available in BigQuery.

FAQ

What are GA4 custom dimensions?

GA4 custom dimensions are event parameters or user properties that you register in the GA4 admin interface so they become available as dimensions in standard reports and Explorations. In GA4, every piece of data is sent as an event parameter — registering a parameter as a custom dimension simply tells GA4 to surface it in the reporting UI. Without registration, the parameter is still collected and appears in BigQuery exports and DebugView, but it's invisible in standard reports.

How many custom dimensions can GA4 have?

Standard GA4 properties support 50 event-scoped custom dimensions, 25 user-scoped custom dimensions, and 10 item-scoped custom dimensions (for ecommerce). GA4 360 properties have higher limits: 125 event-scoped, 100 user-scoped, and 25 item-scoped. These limits apply to registered dimensions — you can send far more parameters than these limits, but only registered parameters appear in the reporting interface.

What is the difference between event-scoped and user-scoped custom dimensions?

Event-scoped dimensions are tied to individual events and only apply to the specific event that sends the parameter. For example, a content_group parameter on a page_view event is only associated with that page_view. User-scoped dimensions are tied to the user profile and persist across all future events until the value is overwritten. A subscription_tier set as a user property applies to every event from that user going forward. Use event-scoped for data that varies per interaction; use user-scoped for stable user attributes like account type or plan level.

How do I register a custom dimension in GA4?

Go to Admin → Custom Definitions → Custom Dimensions and click Create Custom Dimension. Enter a display name for the dimension, select the scope (Event or User), and enter the exact parameter name as it appears in your dataLayer or gtag calls. The parameter name must match exactly — including case. After saving, the dimension will start appearing in reports and Explorations for data collected from that point forward. Historical data is not backfilled in the reporting interface, though it remains in BigQuery.

Why are my custom dimensions not showing in reports?

There are several common reasons. First, check that the dimension is registered — parameters are only visible in reports after registration in Admin → Custom Definitions. Second, verify the parameter name matches exactly (case-sensitive) between your implementation and the registered dimension. Third, note that registration is not retroactive: only data collected after registration appears in reports. Fourth, check that the parameter is actually being sent — use DebugView or the GA4 Realtime report to confirm the parameter is arriving. If the dimension shows no data, also confirm you haven't hit the property's dimension slot limit.

Can I delete a custom dimension in GA4?

You can archive (soft-delete) a custom dimension in GA4, but you cannot permanently delete it. Archiving removes the dimension from reports and makes the slot available again after approximately 48 hours. Archived dimensions remain visible in the Admin panel and can be restored if needed. Historical data associated with the dimension is retained in BigQuery. Because deletion is not instant, avoid registering dimensions speculatively — plan your dimension schema carefully to avoid exhausting your slots.

What is the character limit for custom dimension values?

GA4 custom dimension values (event parameter values) are limited to 100 characters. Values longer than 100 characters are truncated at the collection point. User property values are also limited to 36 characters. For URLs or other long strings, consider hashing, truncating, or using a shorter identifier before sending the value to GA4. The dimension name (the display name in the admin) can be up to 80 characters, and the event parameter name used in your code can be up to 40 characters.

Do custom dimensions affect GA4 sampling?

Custom dimensions themselves do not cause sampling. GA4 standard properties use unsampled data for most reports and Explorations. However, Explorations that query very large date ranges or apply complex breakdowns — including on custom dimensions — may trigger sampling thresholds in high-traffic properties. GA4 360 provides higher data thresholds before sampling applies. If you encounter sampled Explorations, try narrowing the date range, reducing the number of dimensions in the query, or using BigQuery for unsampled analysis of your custom dimension data.