A custom dimension lets you report on information GA4 doesn't collect by default, like blog author, membership level, or form name. You create one in Admin > Data display > Custom definitions by registering an event parameter you're already sending. Standard properties allow up to 50 event-scoped and 25 user-scoped custom dimensions, and data appears within 24 to 48 hours (it is not retroactive).
GA4 tracks a lot out of the box, but it doesn’t know the things that are specific to your business. It can’t tell you which blog author drives the most engaged readers, or whether paid members behave differently from free ones. Custom dimensions fill that gap.
This guide shows you what a custom dimension is, the three types, and how to create one step by step.
Before you start: A custom dimension reports on an event parameter you’re already sending to GA4. If you haven’t set up the underlying event yet, start with the GA4 events guide. You’ll also need the Editor role on the property.
What a custom dimension actually is
Every event in GA4 can carry extra details called parameters. A page_view event, for example, can carry a parameter like author with a value of “Ryan.”
GA4 collects those parameters, but it won’t show them in your reports until you register them. A custom dimension is that registration. It tells GA4: “take this parameter and make it something I can break my reports down by.”
Here’s what that means with an example. Say every article on your blog sends an author parameter. Create a custom dimension for it, and you can suddenly see pageviews, engagement time, and key events split by author, right inside your standard reports.
The three scopes
When you create a custom dimension, you pick a scope. The scope decides what the value attaches to. Choose carefully, because you can’t change it later.
| Scope | Attaches to | Example |
|---|---|---|
| Event | A single event | The author of the article someone viewed |
| User | The person, across sessions | Membership level (free vs paid) |
| Item | A product in e-commerce | Product color or size |
Most of the time you’ll use event-scoped. Reach for user-scoped when the value describes the person rather than a single action, and item-scoped only for e-commerce product details.
First, make sure the parameter is being sent
This is the step people skip. A custom dimension doesn’t create data. It exposes data you’re already collecting.
So before you register anything, confirm the parameter is actually reaching GA4. The usual way to send one is through Google Tag Manager or the gtag code on your site. You can check it’s arriving in Admin > DebugView while you trigger the event.
If the parameter isn’t in your data yet, the custom dimension will sit empty no matter what.
How to create an event-scoped custom dimension
Once the parameter is flowing, registering it takes about a minute.
Step 1: Open Custom definitions
Go to Admin > Data display > Custom definitions, then make sure you’re on the Custom dimensions tab.
You should see: A table of any custom dimensions you’ve already created, with a Create custom dimensions button in the top right.
Step 2: Start a new dimension
Click Create custom dimensions. A panel opens on the right.
Step 3: Fill in the details
Complete the fields:
- Dimension name: what you’ll see in reports, for example
Author. Spaces and underscores are fine, but hyphens aren’t allowed. - Scope: choose Event. Remember, this can’t be changed after you save.
- Description: optional, but a note like “blog post author from the author parameter” helps future you.
- Event parameter: the exact parameter name from your code, for example
author. This also can’t be changed later, so double-check the spelling.
Step 4: Save
Click Save.
You should see: Your new dimension in the Custom dimensions table. It won’t have data right away.
New custom dimensions take 24 to 48 hours to start showing values, and they only report on data collected from the moment you created them. Google spells out the steps in Create event-scoped custom dimensions.
Limits you should know
Custom dimension slots are limited, so spend them on data you’ll actually report on.
- 50 event-scoped custom dimensions per standard property.
- 25 user-scoped custom dimensions per standard property.
- After you delete a custom dimension, you have to wait 48 hours before that slot frees up for a new one.
The full table is in Google’s Configuration limits. If you need more, that’s one of the reasons businesses upgrade to Analytics 360.
Where your custom dimension shows up
Once it has data, you can use your custom dimension in three places:
- As a secondary dimension in most standard reports (the ”+” next to the primary dimension).
- As a dimension or breakdown in the Explore workspace, where it’s most flexible.
- As a field in Looker Studio when you build a dashboard on your GA4 data.
Common mistakes to avoid
Registering before sending. The parameter has to exist in your data first. An empty dimension almost always means the parameter isn’t being sent.
Choosing the wrong scope. You can’t change scope after saving. If the value describes the person, pick user-scoped, not event.
Mismatched parameter names. author, Author, and article_author are three different parameters. The name in GA4 has to match your code exactly.
Burning slots on one-offs. With 50 event-scoped slots, be deliberate. Register the parameters you’ll report on, not every value you happen to send.
What to do next
You’ve got a custom dimension reporting on data that’s unique to your business. Here’s where to go from here:
- See it in action by adding it as a secondary dimension in your standard reports.
- Put it on a dashboard so the breakdown stays in front of you. See how to build a GA4 dashboard.
- Plan your parameters before you send them, so your dimension names stay clean and consistent.
For the bigger picture of how GA4 fits together, start with our GA4 beginner’s guide.