GA4 Custom Dimensions: The Complete Guide for 2025

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 infinitely 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 in 2025: how they work under the hood, the critical registration limits, scope differences, naming conventions, and the four most common mistakes we see in audits.

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.

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.

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)

These limits are significantly lower than the effective limits in Universal Analytics, where you could have 20 custom dimensions per hit but the data model allowed for more creative solutions. 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.

Event-Scoped vs User-Scoped: When to Use Each

Choosing the right scope is critical and is one of the most common sources of errors:

• 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.

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.

How to Register a Custom Dimension

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. Note that 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).

The 4 Most Common Mistakes

1. Not registering parameters:

   This is the #1 issue we see. 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? Remove any that haven't been queried 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: While GA4 theoretically supports longer names, shorter names are easier to work with in queries and reports.

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.

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.

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 — use them strategically and audit regularly.
• Choose the correct scope: event-scoped for data that varies per interaction, user-scoped for stable user attributes.
• 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.