How do I create custom dimensions in GA4?

Applies to: Google Analytics 4 (GA4)
Last updated: May 2025

---

Problem

You want to track additional information—such as user roles, product categories, or content types—that isn’t available in GA4’s standard dimensions. To do this, you need to create custom dimensions.

---

Solution

Custom dimensions in GA4 let you collect and analyze data that’s not included by default. You’ll first need to send the custom parameter with an event (via gtag.js or Google Tag Manager), and then register it as a custom dimension in GA4.

---

Step-by-Step Guide

Part 1: Send a Custom Parameter

Use either gtag.js or Google Tag Manager (GTM) to send a parameter.

Example with gtag.js:

gtag('event', 'sign_up', {
  user_role: 'subscriber'
});

Example with GTM:

1. Go to your GA4 Event Tag
2. In the Event Parameters section, add:
   • Name: user_role
   • Value: {{User Role Variable}} (or hardcoded string)
3. Save and publish the tag

This parameter must be sent with an event before you can register it in GA4.

---

Part 2: Register the Parameter as a Custom Dimension

1. Go to https://analytics.google.com
2. Select your GA4 property
3. Click Admin > Custom Definitions
4. Click Create custom dimension
5. Enter the following:
   • Dimension name: Descriptive name (e.g., “User Role”)
   • Scope: Choose one:
     • Event: Applies to individual events
     • User: Applies to the user across sessions (requires setting the value persistently)
   • Description: Optional
   • Event parameter: Must exactly match what you sent (e.g., user_role)
6. Click Save

---

Viewing Custom Dimensions

Once registered and data is collected:

• Go to Explore > Explorations
• Create a new exploration and add your custom dimension under Dimensions
• Drag it into rows, filters, or segments as needed

It may take up to 24 hours before data starts appearing for new custom dimensions.

---

Notes

• You can create 50 event-scoped and 25 user-scoped custom dimensions per GA4 property
• Custom dimensions apply only to data collected after registration
• To persist values across events for user-scoped dimensions, you must store the value in a user property