A custom dimension lets you add your own descriptive attribute to analytics data. In GA4 you send the value as an event or user parameter and then register it as a custom dimension, after which it appears in reports and explorations. Common SaaS examples include plan tier, account ID type, content category and logged-in status.
Scopes in GA4
Every custom dimension has a scope that decides which data it applies to. Choosing the wrong scope is the most common setup error.
- Event scope: describes one event, such as the form name on a form submission
- User scope: describes the person and persists, such as plan tier or customer status
- Item scope: describes an ecommerce item, such as product category
Setting one up
First send the parameter with your events, through gtag or a data layer variable in Google Tag Manager. Then register it in the GA4 admin under custom definitions, choosing the scope and the exact parameter name. Data appears from registration forward; it is not applied to events collected before the dimension existed.
GA4 caps how many custom dimensions a property can register, with separate limits per scope and higher limits on GA4 360. Check the current limits in Google's documentation before planning a large tracking scheme.
gtag('set', 'user_properties', {
plan_tier: 'growth'
});Cardinality
Dimensions with many unique values, such as full URLs with query strings or unique IDs, can push rows into the (other) bucket in reports. Keep values to a manageable set, and send high-cardinality IDs to BigQuery rather than relying on the interface.
Example
Splitting blog traffic by topic
Suppose Quillbrook, a contract management tool, sends a content_topic parameter with each blog page_view and registers it as an event-scoped custom dimension. The team can now see which topics produce demo requests, instead of reading hundreds of individual URLs.
Common mistakes
Registering before sending, or with a typo
The registered parameter name must match exactly what the tag sends, including case.
Using a dimension for personal data
Emails, names and similar identifiers are not allowed in GA4 and create privacy risk.
Questions
Not in GA4 reports. If you export raw events to BigQuery, any parameters you were already sending are available there even before registration.
