GA4 Custom Events and Custom Dimensions

Google describes a custom event as "an event that you define so you can collect information about an interaction that's important to your business." The details of that interaction travel as event parameters, and to see them in reports you create custom dimensions and metrics. This guide uses Google Analytics Help and the GA4 developer documentation, checked on 7 November 2026.

Check the existing events first

GA4 has three kinds of events before you get to custom ones:

• Automatically collected events, such as page_view, first_visit and session_start, sent by the Google tag on its own.
• Enhanced measurement events, such as scrolls, outbound clicks and file downloads, switched on per web data stream.
• Recommended events: names and parameters Google has defined but does not send for you, because they "require additional context to be meaningful." Examples are generate_lead ("submits a form or a request for information"), sign_up, login, search, and the ecommerce set from view_item to purchase (covered in our GA4 ecommerce tracking guide).

Google's advice on the custom events page is to check those lists before you invent a name: "It's always better to use an existing event because these events automatically populate dimensions and metrics that are used in your reports." A contact form, for example, fits generate_lead. The parameters Google lists for a recommended event fill the built-in dimensions, and sending them also lets you, in Google's words, "benefit from future features and integrations as they become available." A custom event is for the action no list covers, such as a calculator being used or a brochure being requested.

Sometimes the action is already partly measured. If you only want to count views of a thank-you page, Google suggests you can create or modify an event inside GA4 instead of changing your site's code, and then mark it as a key event. Tell whoever edits the site code, or the same action may be counted twice. Google also notes that modified and new events "do not apply to historical data."

Sending a custom event and its parameters

A custom event is a name plus optional parameters. In the GA4 developer guide, a site using the Google tag sends one with the gtag() function, placed below the Google tag snippet:

gtag('event', 'tutorial_complete', {
  tutorial_name: 'Introduction to GA4'
});

Here tutorial_complete is the event name and tutorial_name is an event parameter. In Google Tag Manager you do the same with a Google Analytics event tag: you type the event name, then add rows under Event Parameters whose values come from variables such as Click Text or a data layer variable. Our Google Tag Manager guide covers tags, triggers and publishing.

Google's event parameters guide adds that you can set a parameter for one event, or for every event on the page through the config or set command. To describe the visitor rather than one action, use a user property. Google's user properties page shows the Google tag form:

gtag('set', 'user_properties', {
  favorite_composer: 'Mahler'
});

Once a user property is set, Google says "it will be applied to all future events for that user (including in future sessions)" and "will not apply to events that happened before the user property was set." Do not put names, email addresses or other personal data in parameters or user properties, and do not use a user property for a login ID. That is what User-ID is for, as our GA4 User-ID guide explains.

Registering custom dimensions and metrics

This is the step most setups miss. GA4 collects your custom parameters, but its reports do not show them. The developer guide puts it plainly: "Without this registration, the parameter data is collected but isn't available for reporting." Recommended event parameters you send with their prescribed names fill built-in dimensions. Your own parameters need a custom dimension (for text such as a service name) or a custom metric (for numbers).

Google's steps for an event-scoped custom dimension, which need the Editor role or higher:

1. In Admin, under Data display, click Custom definitions.
2. On the Custom dimensions tab, click Create custom dimensions.
3. Enter a dimension name. It appears in reports; hyphens are not allowed, underscores and spaces are.
4. Choose the scope (Event, User or Item).
5. Enter the exact parameter or user property name your code sends, and save.

Scope and the parameter name cannot be changed after you save, so check the spelling in DebugView before you register. Google says you can add the new dimension to reports "after 24-48 hours from when the custom data was sent and the custom dimension was created."

Custom metrics are created on the Custom metrics tab of the same page. Google says they "are always event scoped." You pick a unit: standard, currency, distance or time. A currency metric must be marked as cost and/or revenue data, which lets you hide it from users whose roles restrict cost or revenue metrics. Calculated metrics, which combine existing metrics into a new one, have their own tab on the same Custom definitions page.

Event, user and item scope

• Event scope describes one action: which button was clicked, which service a quote was for, which payment type was chosen.
• User scope describes the person across their visits, such as a customer tier or a preferred language, and reads from a user property.
• Item scope describes products inside the items array of an ecommerce event such as add_to_cart or purchase, for example a colour or a size. Google notes that you "can't add an item-scoped custom dimension to standard reports"; you use it in explorations and audiences.

Event- and user-scoped dimensions can be added to detail reports, used in explorations (import them from the Custom tab in the Variables column) and used as conditions when you build an audience. Our GA4 explorations guide covers the exploration side.

Limits Google sets

Google's table of how many custom definitions a property can hold:

If you reach a limit, Google says "you'll need to wait 48 hours after deleting dimensions to add new ones." The Quota information link on the Custom definitions page shows how many you have used.

Separate collection limits apply to the data you send. GA4 does not log anything over them: event names and parameter names up to 40 characters, up to 25 parameters per event, parameter values up to 100 characters (page_title, page_referrer and page_location have longer limits), 25 user properties per property, user property names up to 24 characters and values up to 36. There is no limit on distinctly named events for web data streams; apps are limited to 500 per app user. Google adds that an event name over 40 characters will not be reported as a key event.

Naming rules and reserved names

From Google's event naming rules:

• Event names are case sensitive: my_event and My_Event are two different events.
• They must start with a letter and use only letters, numbers and underscores, with no spaces.
• Some names are reserved on the web, including page_view, click, scroll, session_start, first_visit, form_start and form_submit.
• Parameter names such as user_id, session_id, gclid and currency cannot be used for custom dimensions and metrics, and parameter names cannot start with _, firebase_, ga_, google_ or gtag.

User property names are case sensitive too, so Plan and plan become two properties. Pick one style, usually lowercase with underscores, and write the names down before anyone starts tagging.

High cardinality and the (other) row

Cardinality is the number of different values a dimension has. Google's cardinality page defines high-cardinality dimensions as those "with more than 500 unique values in one day." They add rows to reports, which makes it more likely a report hits its row limit and groups the rest under (other).

Google's examples of custom dimensions to avoid are a unique ID per user (use User-ID instead), a session ID and a timestamp. It also warns that registering a parameter that is already a built-in dimension, such as page or transaction ID, "will use one of your custom dimension quota." One more trap: GA4 treats any custom dimension value that looks like a number as a number, so text such as "94E40" turns into scientific notation.

Why a new dimension shows (not set)

Google's (not set) article calls it "a placeholder name that Analytics uses when it hasn't received any information for a dimension." For custom parameters, it lists these causes:

• The first 24 hours. You may see (not set) "during the first 24 hours after you register a custom parameter."
• session_start and first_visit. These keep the parameters of the first event of the session only, so a value sent later shows (not set) next to them.
• A User ID registered as a custom dimension, which Google recommends against.

Two more cases follow from how dimensions work. A dimension built from a parameter on your quote event has no value on rows for events that never carry it, such as page_view, so (not set) there is expected. And a parameter name with different spelling or case from the one you registered gives an empty dimension, because the name you registered never arrives. Our DebugView guide shows how to see each event's parameters as they arrive.

A setup checklist

1. Write down each action you want to measure and look it up in the recommended events list first.
2. Name custom events and parameters in lowercase with underscores, within 40 characters, avoiding reserved names.
3. Send only values with a limited set of options as dimensions: a service, a form name, a plan. No IDs, timestamps or personal data.
4. Test in DebugView that each event arrives with the right parameter names and values.
5. Register each parameter you want to report on in Custom definitions, with the right scope.
6. Wait 24 to 48 hours, then check the dimension in a report or exploration.
7. Mark the events that matter as key events.

New to GA4? Start with our GA4 basics guide, which covers installing the tag and key events.

Frequently asked questions

Why can't I see my event parameters in GA4 reports?

Custom parameters have to be registered as custom dimensions or metrics under Admin, Custom definitions. Until then GA4 collects them but does not show them in reports. After registering, allow 24 to 48 hours.

What is the difference between a custom event and a custom dimension?

A custom event counts an action, such as a quote request. A custom dimension makes one of the details sent with that event, such as the service chosen, available in reports.

How many custom dimensions can a GA4 property have?

A standard property can have 25 user-scoped, 50 event-scoped and 10 item-scoped custom dimensions, plus 50 custom metrics and 5 calculated metrics. Analytics 360 properties have higher limits.

When does a new custom dimension show data?

Google says you can use it in reports 24 to 48 hours after the data was sent and the dimension was created, and a user property only applies to events after it was set. Register dimensions as soon as you start sending the parameter.

Can I change a custom dimension after creating it?

Not the scope or the parameter or user property it reads: Google says neither can be changed after you save. If either is wrong, you need a new custom dimension, which uses another slot of your quota.

Should I use a custom event or a recommended event?

Use a recommended event whenever one fits, such as generate_lead for a form enquiry. It fills built-in dimensions and reports. Use a custom event only when no automatic, enhanced measurement or recommended event covers the action.

Want your GA4 events and custom dimensions set up properly? See our services or email [email protected].