Custom Dimensions

What Custom Dimensions Are

Custom dimensions are extra attributes you attach to your Google Analytics data so you can slice reports by information that GA4 doesn't collect on its own — things like membership tier, article author, logged-in status, or content category. In GA4 they're built by registering an event parameter or a user property, which is a different mechanism from the index-slot system Universal Analytics used.

The stakes are simple: if a dimension isn't registered, GA4 quietly drops it from your standard reports and explorations, and you can't backfill it. Get the setup right up front or you lose the segmentation you were counting on.

Event-Scoped vs User-Scoped (the part people get wrong)

GA4 has two scopes that matter day to day. An event-scoped custom dimension is registered from an event parameter and describes a single hit — the category of the page someone just viewed, for instance. A user-scoped custom dimension comes from a user property and sticks to the person across sessions — their plan level, their preferred language, whether they're a returning customer. (There's also an item scope for GA4 ecommerce, set on products in the items array.)

Pick the wrong scope and your numbers look insane. If you register "membership_level" as event-scoped but only send it on the login event, every other event that user fires shows "(not set)" for that dimension. User scope is what you want there, because it carries the value forward.

A real example

Say you run a recipe site and want to know which content type — "quick" vs "weekend project" — drives the most engaged sessions. You push a parameter on every page_view:

gtag('event', 'page_view', {
  recipe_difficulty: 'weekend_project'
});

Then in Admin → Data display → Custom definitions you register a custom dimension named "Recipe difficulty" with event parameter recipe_difficulty and scope Event. Within 24–48 hours it shows up as a breakdown in the Engagement reports and immediately in Explorations. Now you can compare average engagement time for "quick" vs "weekend_project" head to head.

GA4 Limits You Need to Respect

These caps aren't suggestions — hit them and registration silently fails or your data gets bucketed into "(other)."

That cardinality line is the one that bites people. Don't register a high-uniqueness value like a full URL, a timestamp, or a user ID as a custom dimension — you'll blow past 500 unique values and everything above it collapses into "(other)." Use the built-in reporting identity or BigQuery export for that kind of granularity instead.

How to Set One Up

1. Decide the scope first — does this attribute describe one event, or the whole user? Write it down before you touch anything.
2. Send the data. For event scope, add the parameter to the relevant event (via gtag, Google Tag Manager, or the Measurement Protocol). For user scope, set a user property with gtag('set', 'user_properties', {...}) or GTM's user property tag.
3. Confirm it's arriving. Open Admin → DebugView, trigger the event, and check the parameter or user property shows up on the hit.
4. Register it: Admin → Data display → Custom definitions → Create custom dimension. Give it a clear name, pick the matching scope, and map it to the exact parameter/property name.
5. Wait 24–48 hours for standard reports to populate. Explorations pick it up faster.
6. Validate in an Exploration: drop the new dimension into a free-form table against a metric you trust and sanity-check the "(not set)" row size.

Common Mistakes and How to Fix Them

• Registering before sending data. The definition points at a parameter name; if nothing is ever sent under that exact name, you get a column of "(not set)." Fix: verify in DebugView first, then register.
• Case and spelling mismatches. Recipe_Difficulty in your tag and recipe_difficulty in the definition are two different things to GA4. Fix: copy-paste the parameter name, don't retype it.
• Wrong scope for the question. Registering a lifetime attribute (plan tier) as event-scoped means it's blank on every event you forgot to tag. Fix: use a user property and user scope.
• High-cardinality values. Piping page paths or IDs into a dimension explodes past the 500-value limit and dumps the rest into "(other)." Fix: keep dimension values to a bounded set of categories.
• Burning slots on junk. With only 50 event and 25 user slots, registering test dimensions you never clean up locks out real ones later. Fix: audit custom definitions quarterly and archive dead ones.

FAQ

Do custom dimensions apply retroactively?

No. GA4 only populates a custom dimension from the moment it starts receiving the underlying parameter or property. There is no backfill, so register early even if you're not ready to report on it yet.

What's the difference from Universal Analytics custom dimensions?

UA used numbered index slots (up to 20 on the free tier) with hit, session, user, and product scopes that you set via the tracking code. GA4 dropped the numbered-slot model entirely — you register against event parameters and user properties instead, with event, user, and item scopes. If you migrated, none of your UA definitions carried over.

Why does my custom dimension show "(not set)"?

Three usual causes: the parameter wasn't sent on that event, the name doesn't match exactly, or you used event scope for a value that only fires on some events. Check DebugView to see what's actually on the hit.

Can I use a custom dimension as a segment or in an audience?

Yes. Once registered, custom dimensions are available in Explorations for segmentation and can be used to build audiences and comparisons, which is where a lot of their value comes from.

How many can I create?

On standard GA4: 50 event-scoped, 25 user-scoped, and 10 item-scoped per property. GA4 360 raises these. Archiving a dimension frees the slot.

Related Terms

• Google Analytics
• Segments
• UTM Parameters
• Data Retention