Definition
In GA4Google's event-based analytics platform., data arrives as events carrying named values. Some of those values, such as page location or traffic source, are built into reporting from the start. Anything the business adds for its own purposes, such as the course a form was about or the plan a user is on, is collected and kept with the event but does not appear as a selectable dimension until it is registered. A custom dimension is that registered field: an administrator gives it a display name, chooses its scope and enters the exact parameter or property name it reads from.
GA4 groups custom dimensions and custom metrics together as custom definitions. The distinction is the type of value: a custom dimension holds text used to group and filter, while a custom metric holds a number to be summed or averaged. This page is about the first kind.
Event, user and item scope
Scope is the most consequential choice at registration, because it decides what each value describes and so which reports can use it.
- Event scope describes one event. The form name on a submission or the filter applied on a search is an event-scoped value, and it can differ on every event.
- User scope describes the person and travels with every later event until it changes. It reads from a user property, such as customer tier or the month someone signed up.
- Item scope describes a product inside the item list that e-commerce events carry, such as a colour or a supplier not covered by the standard item fields.
Choosing the wrong scope produces a dimension that technically exists and answers nothing. A customer type registered at event scope cannot answer how many such customers visited; a form name registered at user scope would overwrite itself with every new form. The guide to GA4 reports and dimensions explains how scope also decides which dimensions and metrics can sit together in one report.
In practice: registering, naming and limits
Registration happens in the property's admin area under custom definitions. The parameter name must match what the tag sends exactly, including case, so the naming convention in the tracking plan is the reference to copy from. The display name is what report users will see and should say plainly what the field contains.
Properties have a documented limit on how many custom dimensions they can register at each scope. The limit is comfortable for a site that registers what its reports use and tight for one that registers every parameter by habit. The guide to GA4 events and parameters sets out how to design a schema so that slots go to the fields reports need, and why high-cardinality values such as full URLs or identifiers make poor dimensions. Parameters that are never registered are not lost: they remain in the raw event export for anyone who needs them.
Once registered, a dimension can be used in GA4 explorations, which list registered custom definitions among the prerequisites for building one, and in customised standard reports.
Why history does not backfill
The most common surprise with custom dimensions is the empty past. Registering a parameter today does not make last month's values appear in reports, even though those values were collected; the reporting interface starts filling the dimension from the time of registration, after a short processing delay. GA4 does not reprocess data collected before a change.
That has two practical consequences. Registration belongs in the release that starts sending the parameter, not after the first report request. And when a dimension was added late, the date should be written down where future readers will find it, because a chart that starts mid-year looks like a change in behaviour. The GA4 property handover checklist asks for every custom dimension to be recorded with its purpose, and the guide to marketing data quality includes custom definitions among the configuration to export and check in an audit. The Google Analytics 4 section places custom definitions among the setup work that makes the property useful.
A language school finds its course levels
Parlance Hill Language School sent a course_level parameter, with values from beginner to advanced, on every
enquiry event from March. In June the director asked which levels the 380 enquiries since March had been
about, and the parameter appeared in DebugView but in no report. The analyst registered course_level as an
event-scoped custom dimension on 12 June. From the next day, reports split enquiries by level: in the rest
of June, 61 enquiries arrived, 27 of them for beginner courses. The March to mid-June history was answered
separately from the raw export. The handover document now notes that the dimension starts on 12 June, and the
next three parameters were registered on the day they shipped.
Related terms
An Event ParameterA named value sent with an analytics event that describes it, such as a page location, form name or item price. is the raw value a custom dimension reads; the parameter exists whether or not it is registered. GA4Google's event-based analytics platform. is the platform where registration and scopes apply. A Key EventA GA4 event marked as important to the business, the property's measure of success. is often the event whose parameters most need registering, because they describe the outcomes reports are built around. The Data LayerA structured object on a web page that passes values to a tag manager for tags to use. is where a site usually passes the values that become parameters, so its naming has to match the registration.
Common confusions
- Unregistered parameters are not collected. They are collected and stored; they are only absent from the reporting interface.
- Registering a dimension fills in its history. It applies from the moment of registration onward.
- Any scope will do. The scope decides what the value describes; the wrong one makes the dimension useless for the question asked.
- More custom dimensions mean better reporting. Slots are limited, and fields no report uses waste them.
- A custom dimension and a custom metric are interchangeable. One groups by text, the other adds up numbers.
