How to Create Google Analytics 4 Custom Dimensions Event Scoped

Tracking specific user actions in Google Analytics 4, like which exact button they clicked or which form they submitted, requires using event-scoped custom dimensions. This allows you to collect data unique to your business that GA4 doesn't track automatically. This article provides a complete walkthrough, showing you how to send custom data from your website using Google Tag Manager and then turn that data into a usable dimension inside your GA4 reports.

Graphed

Your AI Data Analyst to Create Live Dashboards

Connect your data sources and let AI build beautiful, real-time dashboards for you in seconds.

Build Your First Dashboard

So, What Exactly Is an Event-Scoped Custom Dimension?

In simple terms, custom dimensions let you analyze data that isn't included in Google Analytics by default. While GA4 automatically tracks things like the page a user visited (page_location) or where they came from (session_source), it can't know the specific details of a custom event on your site without you telling it what to look for.

The term "scope" refers to what the dimension applies to. An event-scoped dimension only applies to the single event it was sent with. Think of it as a one-time piece of information attached to a specific action.

Here are a few practical examples to make it clearer:

• form_submit Event: You could have three different forms on your site: a contact form, a newsletter signup, and a quote request form. By adding an event-scoped custom dimension called "Form Name," you can see which specific form was submitted each time the form_submit event fires.
• sign_up Event: On a pricing page, a user might sign up for a "Free," "Pro," or "Enterprise" plan. An event-scoped custom dimension like "Plan Type" would tell you which plan was chosen.
• share Event: When a user shares a blog post, you could capture the "Article Author" as a custom dimension to see which writers' content gets shared the most.

Without custom dimensions, a click is just a click, and a form submission is just a form submission. Event-scoped dimensions give you the rich context needed to understand user behavior on a much deeper level.

AI for Data Analysis

Crash Course

Graphed

Free PDF Guide

AI for Data Analysis Crash Course

Learn how to get AI to do data analysis for you — the best tools, prompts, and workflows to go from raw data to insights without writing a single line of code.

Download Free Guide

The Process: Two Essential Pieces to This Puzzle

Setting up event-scoped custom dimensions is a two-part process that involves both Google Tag Manager (GTM) and Google Analytics 4. It's crucial to understand how they work together.

1. Send the Data (Google Tag Manager): First, you need to capture the information you want to track on your website and send it to Google Analytics. This piece of information is called an event parameter. GTM is the tool you'll use to configure this.
2. Register the Data (Google Analytics 4): Once GA4 starts receiving your new event parameter, you have to tell it what to do with that information. By "registering" the parameter as a custom dimension, you're making it available for use in your reports and explorations.

You must complete both steps for this to work. If you send a parameter from GTM but never register it in GA4, the data will be ignored in standard reporting. Likewise, if you register a dimension in GA4 but never set up the tag to send the data from your site, your new dimension will always be empty.

Step-by-Step Guide: Setting Up Your First Custom Dimension

Let's walk through a common real-world scenario: You have a pricing page with several calls to action (CTAs), and you want to know which one your visitors click the most.

Let's imagine your page has these three buttons:

• "Get Started for Free"
• "Start Pro Trial"
• "Request Enterprise Demo"

We'll create a custom event called cta_click and a custom dimension called "Button Text" to capture the text of the button that was clicked.

Graphed

Your AI Data Analyst to Create Live Dashboards

Connect your data sources and let AI build beautiful, real-time dashboards for you in seconds.

Build Your First Dashboard

Part 1: Send the Parameter with Google Tag Manager

First, log in to your Google Tag Manager container and follow these steps.

Step 1: Enable the "Click Text" Built-In Variable

GTM has many built-in variables that can capture information from your site automatically, but many of them are turned off by default. "Click Text" is exactly what we need for this task.

• In the left-hand menu, navigate to Variables.
• Under the "Built-In Variables" section, click Configure.
• Scroll down to the "Clicks" section and check the box next to Click Text.

Step 2: Create a Trigger to Isolate Your Button Clicks

Next, we need a trigger that only fires when a user clicks one of our specific pricing page buttons, not just any link or button on the website.

• In the left-hand menu, navigate to Triggers and click New.
• Give your trigger a clear name, like "Trigger - Clicks on Pricing Page CTA Buttons."
• For the "Trigger Configuration," select Just Links under the "Click" section. You might choose "All Elements," but "Just Links" often works well if your buttons are wrapped in anchor (<a>) tags.
• Set the trigger to fire on Some Link Clicks.
• Now, set the condition for the trigger. This part depends on your website's code. You need to find a unique identifier for your pricing buttons. A great option is a shared CSS class. Let's assume all your pricing CTAs have the class pricing-btn. Set the condition to: Click Class contains pricing-btn
• Click Save.

Tip: Don't know how to find the Click Class? In GTM's Preview mode, click your button and check the "Variables" tab in the Tag Assistant window. You can see the value Click Classes provides.

Step 3: Create the GA4 Event Tag

Now, let's create the tag that sends our custom event and parameter to GA4.

• In the left-hand menu, navigate to Tags and click New.
• Name your tag something descriptive, like "GA4 Event - Pricing Page CTA Click."
• For "Tag Configuration," choose Google Analytics: GA4 Event.
• In the "Configuration Tag" field, select your existing GA4 configuration tag.
• For Event Name, enter cta_click. Remember to use lowercase letters and underscores instead of spaces.
• Under the Event Parameters section, click Add row.
• In the Parameter Name field, type button_text. This must be precise!
• In the Value field, click the lego brick icon and select {{Click Text}} from the list.
• Attach your trigger: Under "Triggering," select the trigger you created in the previous step ("Trigger - Clicks on Pricing Page CTA Buttons").
• And… Save the tag.

Step 4: Preview and Push Live!

Always test your changes before publishing. Click the Preview button in GTM, connect to your site, and click one of your pricing buttons. In the Tag Assistant window, you should see your "GA4 Event - Pricing Page CTA Click" tag has fired. Click on it, and you'll be able to see that the button_text parameter was sent with the correct value (e.g., "Start Pro Trial"). Once you confirm everything is working, click Submit in GTM to publish your changes.

Part 2: Register the Dimension in Google Analytics 4

Now that GTM is sending the button_text parameter, we need to tell GA4 to recognize it as a reportable dimension.

Step 1: Navigate to Custom Definitions

• Log in to your GA4 property.
• Go to Admin (the gear icon at the bottom-left).
• Under the "Data display" column, click on Custom definitions.

Step 2: Create the Custom Dimension

• Click the blue Create custom dimensions button.
• Fill out the form:
• Finally, click Save.

That's it! You're done. Now, you just have to be patient.

AI for Data Analysis

Crash Course

Graphed

Free PDF Guide

AI for Data Analysis Crash Course

Learn how to get AI to do data analysis for you — the best tools, prompts, and workflows to go from raw data to insights without writing a single line of code.

Download Free Guide

Where to Find and Use Your New Dimension

Here's a key detail: Your new custom dimension data can take 24 to 48 hours to appear in standard reports. However, you can often see it much sooner in two places: the Realtime report and in GA4's Explore section.

The best way to analyze this data is with an Exploration report:

1. Click on Explore in the left sidebar and start a new Free form exploration.
2. In the "Variables" column, find DIMENSIONS and click the + button.
3. Search for your newly created "Button Text" dimension, check the box, and click Import.
4. Drag the "Button Text" dimension from the Variables column over to the Rows configuration box.
5. Drag the Event count metric over to the Values box.
6. Finally, at the bottom, add a Filter for Event Name exactly matches cta_click.

Your report will now show a clean table with a count of clicks for each unique button text, giving you clear insight into which CTA is performing best.

Final Thoughts

Setting up event-scoped custom dimensions is an incredibly powerful way to get more granular, actionable insights from Google Analytics 4. The process is straightforward once you understand the two-part connection: first sending the data as an event parameter from GTM, and then registering that parameter as a dimension within GA4.

While GA4's default setup is a great starting point, this customization is what helps you truly understand how users interact with your specific website. Juggling configurations in Tag Manager, waiting for data to populate, and then building custom reports is an effective but time-consuming process. At Graphed, we’ve streamlined this entire workflow. Once we integrate with your tools like Google Analytics, you can just ask in plain language, 'Show me which CTA buttons got the most clicks last month,' and instantly get a live, automated report. We believe that getting answers from your data should be a matter of seconds, not hours.