Custom Events allow you to track specific user interactions and behaviors on your website that go beyond standard pageviews and clicks. With Custom Events, you can measure actions like form submissions, video plays, button clicks, file downloads, and any other custom interactions that matter to your business.

Custom Events are user-defined tracking points that capture specific actions visitors take on your website. Unlike automatic tracking that records all clicks and pageviews, Custom Events let you focus on the interactions that are most important to your conversion goals and user experience optimization.

Targeted Tracking: Focus on the specific user actions that drive your business objectives rather than sorting through all generic click data.

Better Analysis: Understand how users interact with key elements like CTA buttons, form fields, video content, and interactive features. You'll be able to use these insights to filter through the rest of your data.

Simple Creation: Track virtually any element of your website by grabbing the CSS selector and wait for the data to roll in.

You can create Custom Events in two different ways:

This second method is convenient when you're already analyzing data and want to quickly create and apply a new Custom Event without leaving your current workflow.

Finding the right CSS selector is the key to setting up Custom Events correctly. Here's a step-by-step guide:

Chrome, Edge, or Brave:

Firefox:

Safari:

Once Developer Tools are open, you'll see the HTML code. The element you clicked should be highlighted. It might look something like this:

html

Look for identifiers in this order of preference:

1. ID (Best option if available)

2. Unique Class Name

3. Combination of Classes

4. Element with Attribute

Chrome/Edge Method (Easiest):

Manual Method:

Before saving your Custom Event, test that your selector works:

Tracking a specific button by ID:

#signup-button

Tracking all "Add to Cart" buttons with the same class:

.add-to-cart-btn

Tracking a form submission button:

form#contact-form button[type="submit"]

Tracking a navigation link:

nav a[href="/pricing"]

Tracking any element with specific text (use carefully):

button:contains("Download")

Be Specific Enough: Your selector should only match the element(s) you want to track. Too broad and you'll track unwanted clicks.

Avoid Overly Complex Selectors: Selectors like div > div > div.class > span can break if your website structure changes. Use IDs or specific classes when possible.

Use Stable Identifiers: Choose IDs or classes that are unlikely to change. Avoid classes like .btn-1 or .element-a7f2 that look auto-generated.

Test on Multiple Pages: If your element appears on different pages, test that your selector works consistently across all of them.

Track when users click on specific elements like buttons, links, images, or any clickable element. This is the most common Custom Event type.

Use for:

Track when users view a page that contains a specific element. Useful for tracking exposure to important content or reaching specific sections.

Use for:

After creating a Custom Event, you can monitor whether it's firing correctly:

Important: It takes approximately 30 minutes for event data to start populating in the Event Log. This is a great way to verify your CSS selector is working correctly before relying on the data for analysis.

In the Custom Events section of Settings, you'll see an overview of all your events with key metrics:

The real power of Custom Events comes from using them as filters across all Heatmap features. Once an event is created and collecting data, you can filter by it to focus your analysis.

Interpretation tip: This helps you understand how users who perform specific actions (like clicking your CTA) behave differently on your pages compared to all visitors.

Interpretation tip: Watch recordings of users who completed important actions to understand their journey, or filter by events that should happen but have low counts to see where users are getting stuck.

Interpretation tip: Compare funnel performance between users who engaged with certain elements (like watching a demo video) versus those who didn't, to measure the impact of that engagement on conversions.

Interpretation tip: Segment your traffic data by Custom Events to understand which pages, sources, or devices correlate with your most valuable user actions.

You can combine Custom Events with other filters like:

This allows for powerful segmentation.

Use Clear Naming Conventions: Choose event names that are descriptive and consistent across your team.

Don't Over-Track: Focus on meaningful interactions rather than tracking every possible action. Too many events can make analysis overwhelming.

Include Relevant Properties: Add context to your events with properties that will help with future analysis.

Test Before Deploying: Always test your Custom Events in a development environment before pushing to production.

Document Your Events: Keep a reference guide of all Custom Events, their purpose, and where they're implemented.

If your Custom Event isn't working as expected, here's how to diagnose the issue:

If the event is firing in the Event Log: Your Custom Event is set up correctly and data should start appearing in your reports within 30 minutes.

If the event is NOT firing in the Event Log: Your CSS selector likely isn't matching the correct element.

The most common issue is an incorrect CSS selector. Double-check:

If you've verified your CSS selector is correct and the event still isn't firing in the Event Log, please contact our support team at support@heatmap.com. Our team will need to review the issue internally to identify and resolve any technical problems with event tracking.

If you have questions about setting up Custom Events or need assistance with implementation, contact our support team at support@heatmap.com or visit our Help Center for additional resources.