Custom Events are user-defined tracking points that let you monitor specific interactions on your website, such as button clicks, form submissions, or page views of important elements. Unlike standard tracking that captures all clicks and pageviews, Custom Events help you focus on the actions that matter most to your business goals. They allow you to filter your heatmaps, recordings, funnels, and analytics data to understand how users who perform specific actions behave differently from your general audience.

Standard tracking automatically captures all pageviews and clicks across your website, which can result in a lot of data to sift through. Custom Events let you specifically identify and track only the interactions you care about like a "Sign Up" button click or viewing your pricing page, so you can quickly filter and analyze behavior around those key moments without noise from other data.

There is no specific limit to how many events you can create.

Yes, Custom Events work across all devices: desktop, mobile, and tablet. Once you create a Custom Event, it will automatically track the specified interaction regardless of which device your users are on. You can then filter your data by device type to see how behavior differs across platforms.

Yes, if the element has the same CSS selector across multiple pages, one Custom Event will track it everywhere it appears. For example, if you have a "Contact Us" button with the class .contact-button on every page of your site, a single Custom Event using that selector will track clicks on all of them. If the selectors differ between pages, you may need to create separate events or use a condition like "CSS Selector contains" to capture variations.

Both methods create the same Custom Event with the same configuration options. The difference is workflow convenience:

Click Events fire when a user clicks on an element matching your CSS selector. Use these for tracking button clicks, link clicks, or any interactive element.

Page View Events fire when a user views a page that contains an element matching your CSS selector. Use these to track whether users reach specific pages or see important content sections. The user doesn't need to click anything.

Example: Use a Click Event to track clicks on a "Buy Now" button, or use a Page View Event to track when users reach a checkout page that contains a specific element like #checkout-container.

CSS Selector equals: Use when you know the exact, complete selector. Best for precise tracking when you want to match only exact elements.

CSS Selector contains: Use when you want to match elements that include a certain string in their selector. Useful for tracking multiple similar elements or when selectors have dynamic parts.

Other conditions:

Yes, you can edit Custom Events after creation. When viewing your Custom Events in Settings, click on the event you want to modify. You can update:

Changes take effect immediately, but keep in mind that editing the CSS selector will change what gets tracked going forward.

Historical data remains unchanged as it reflects what was tracked with the previous selector. Once you update the CSS selector, new data will be tracked based on the new selector. This means you may see a shift in your metrics after the change. If you need to maintain historical consistency, consider creating a new Custom Event instead of editing the existing one.

Currently, there's no duplicate function, but you can manually create a new Custom Event with the same settings as an existing one. Simply reference the original event's configuration and create a new event with those same parameters.

Yes, you can delete Custom Events from the Settings → Custom Events section by clicking the three dots and selecting delete. When you delete an event:

Make sure you truly want to remove the event before deleting it.

Absolutely! You don't need to be a developer. Follow the step-by-step instructions in the main guide:

The browser does all the technical work for you. Just make sure to test that your selector is working in the Event Log after creation.

The easiest method:

This works in Chrome, Edge, and Brave browsers and gives you a working selector automatically.

If your selector is too broad, try these approaches in order:

The goal is to have only your intended element(s) highlighted.

Prefer IDs when available (#signup-button):

Use classes when IDs aren't available (.cta-button):

Yes, each Custom Event can use multiple conditions (equals, contains, starts with, etc.). You can also:

"CSS Selector contains" matches any element whose selector includes the text you specify. It's useful when:

Use it when "equals" is too strict but you still want to maintain some specificity.

To create selectors that survive website updates:

Yes, Custom Events will track dynamically added elements as long as they match your CSS selector. This works for:

The tracking automatically detects when these elements appear and match your selector.

After creating a Custom Event, it takes approximately 30 minutes for data to start appearing in the Event Log and reports. This processing time is normal. If you don't see data after 30 minutes, check your CSS selector in the Event Log to verify the event is firing correctly.

If events appear in the Event Log but not in reports, this usually means:

Try expanding your date range or removing other filters to see if data appears.

Custom Events track sessions, not individual identified users. However, you can:

This maintains user privacy while still giving you behavioral insights.

You can export data from reports and analytics that include Custom Event filters. When viewing a filtered report (heatmaps, analytics, etc.), look for export options within that feature. The exported data will reflect the Custom Event filter you've applied.

Custom Events only track data from the moment they're created going forward. They don't retroactively capture historical data. If you create a Custom Event today, it will start collecting data from today onward. Plan your Custom Events early if you need long-term trend data.

Custom Events can be used as powerful filters to analyze goal completions and conversions. While Custom Events themselves aren't goals, you can:

When viewing Custom Event data, you can adjust the date range to analyze different time periods. The metrics (Count, Sessions, Counts per Session) will update to reflect only the data within your selected range. This lets you compare performance over time or focus on specific periods.

Yes, you can apply multiple Custom Event filters simultaneously. This shows you data from sessions where all selected events occurred. For example, filter by both "Clicked CTA" and "Viewed Page" to analyze users who did both actions.

Yes! Custom Events can be combined with all standard filters including:

You can then watch these recordings to understand the full user journey of people who completed that specific action.

Yes, in Analytics you can filter by Custom Events to create behavioral segments. Go to Analytics → Filters → select your Custom Event. All analytics data will then be segmented to show only sessions containing that event, letting you understand traffic sources, pages, and behaviors specific to that segment.

For example, compare heatmaps of "users who clicked Buy Now" vs. "all users" to see if engaged users interact with your page differently.

Yes! In Funnels, you can apply Custom Events as filters to analyze conversion rates specifically for users who triggered that event. This helps you understand whether certain interactions (like watching a demo video or clicking a specific CTA) correlate with higher conversion rates through your funnel.

Follow this checklist:

If none of these resolve the issue, see "Still Not Working?" below.

If events appear in the Event Log but not in feature reports:

If an event count seems higher than expected:

Test your selector in Developer Tools (Ctrl+F / Cmd+F) to see how many elements it matches. If it's highlighting multiple elements, make your selector more specific.

Website updates often change HTML structure, which can break CSS selectors. Common causes:

Go back to your website, inspect the element again, and update your Custom Event with the new CSS selector.

If you've verified your CSS selector is correct and the event still isn't firing in the Event Log after 30 minutes, contact support at support@heatmap.com. Include:

Our team will investigate and resolve any technical issues with event tracking.

Focus on quality over quantity. Start with 5-10 events for your most important interactions:

You can always add more later. Too many events from the start makes analysis overwhelming and harder to maintain.

Use clear, descriptive names that your whole team can understand:

Good names:

Poor names:

Consider including the location (page or section) and the action in the name for clarity.

It depends on your analysis needs:

One event for all instances: Use if you want to track total engagement with that button type across your site

Separate events by page: Use if you need to compare performance across different pages

You can also use one event with page-level filters in your reports to achieve similar segmentation.

Yes! You have two approaches:

Track the submit button click: Create a Click Event targeting the submit button's CSS selector

Track the success page view: Create a Page View Event for a confirmation or thank-you page that appears after submission

The submit button method is usually more reliable as it tracks the submission attempt, while the success page method only tracks completed submissions.

For multiple sites:

No, Custom Events don't impact your website's performance. The tracking happens through the existing Heatmap script already on your site. Custom Events simply configure what that script monitors. They don't add extra weight or loading time to your pages.

No updates needed! Custom Events work with your existing Heatmap tracking script. As long as the standard tracking script is installed on your site, you can create and use Custom Events immediately without any code changes.

Yes, Custom Events work with single-page applications built with frameworks like React, Vue, or Angular. Since Custom Events track based on CSS selectors and DOM elements, they'll fire whenever matching elements are clicked or viewed, regardless of whether it's a traditional page load or a dynamic view change in an SPA.

Custom Events can only track elements within the same domain as your Heatmap tracking script. If you have an iframe from a different domain (like an embedded video or third-party form), you cannot track interactions inside that iframe. However, you can track clicks on the iframe container itself if needed.

You can track virtually any HTML element that can be identified with a CSS selector:

The element doesn't need to be clickable for Page View events; it just needs to exist on the page.

Yes, Custom Events follow the same privacy rules as all Heatmap tracking. If a user has opted out of tracking or hasn't provided consent (depending on your setup), Custom Events won't fire for that user. Custom Events track sessions and behavior, not personally identifiable information.

If your question isn't answered here, contact our support team at support@heatmap.com.