What is a custom event in Umami?
A custom event records a named action in addition to ordinary pageviews. Umami supports HTML data attributes for element interactions and tracker functions for events emitted from your code. Choose the method based on what you need the event to mean: an interaction with an element, or an application state that may occur later.
For an illustrative SaaS signup, a pricing-page click expresses intent, while a successfully created account is a different result. Keep pricing-cta-clicked and signup-completed as separate proposed event names. Counting both under Signup would make a report impossible to interpret when the form fails.
Use an HTML attribute for a click
With the Umami tracker configured on the page, the data-umami-event attribute assigns a name to a tracked element interaction. This is a useful candidate for a pricing call to action or a worksheet download link. Give the name a concrete meaning that will still be clear when viewed without the page open.
An attribute on a submit button records the interaction, not the eventual server response. A user can click twice, fail validation, or lose the connection after the click. Keep this method for the click question and use a success-aware application event for the completion question.
<a href="/signup/" data-umami-event="pricing-cta-clicked" data-umami-event-plan="starter">Start a trial</a>
Use JavaScript when the application confirms success
Umami documents umami.track(event_name, data) for a named event with properties. In your implementation, emit signup-completed from the path that handles a confirmed successful signup. Avoid emitting it merely because the user opened a confirmation URL that can be revisited.
The call below illustrates the event payload, not a complete signup handler. Your application must determine success, handle tracker availability, and prevent duplicate emission appropriately. A blocked or unavailable analytics request should not make account creation fail.
umami.track("signup-completed", {
plan: "starter",
entry: "pricing"
});Keep event properties useful and bounded
Umami supports properties through event data. Data-attribute values are stored as strings, while the JavaScript method supports typed values. The Events view exposes property breakdowns. A small vocabulary such as plan and entry point is easier to compare than a different free-text label for every visit.
For the fictional trial, allow starter or team for plan, and pricing or article for entry. Do not place email addresses, free-text form answers, access tokens, or customer document contents in the proposed payload. Record only what is necessary to answer the measurement question and review the collected data in the actual report.
| Event | Emit when | Do not infer |
|---|---|---|
| pricing-cta-clicked | The pricing link is clicked | An account was created |
| signup-completed | The application confirms the account was created | The person activated or paid |
| first-report-created | The first useful report is successfully saved | Every signup reaches this point |
| upgrade-requested | The user starts the upgrade path | A payment settled successfully |
Verify events before reading conversion totals
Run a successful signup, a validation failure, a repeated click, and a reload of the confirmation screen. Compare the expected events with the report for the same site, time window, and filters. Inspect whether one interaction accidentally emits through both an HTML attribute and a JavaScript handler.
Keep event counts, people, sessions, and business records distinct. A repeated action may legitimately create several events, while browser restrictions may prevent some activity from appearing. Use the product database or billing system for authoritative account and payment state; use the analytics report to understand observed behavior within its collection limits.
Why is my custom event missing or counted twice?
Check that the tracker is configured for the intended site, the event call runs, the event has a name, and the selected report window includes the test. Then inspect blockers and network failures. For duplicate counts, look for multiple handlers, automatic interaction tracking plus a manual call, or success code that reruns after navigation. Reproduce one action at a time before changing the entire event plan.
Sources and editorial method
Official sources linked in this guide were checked on October 28, 2026. Recommendations and fictional examples are editorial analysis, not hands-on product tests or customer results. Features, prices, and plan limits can change; confirm the current documentation before choosing a plan or implementing a workflow.