Skip to main content
Umami allows you to track custom events without writing any JavaScript. Simply add data attributes to your HTML elements, and the tracker will automatically capture user interactions.

​
Basic Event Tracking

To track an event, add the data-umami-event attribute to any HTML element: 
<button data-umami-event="signup-button">Sign Up</button>
When a user clicks this button, Umami will track an event named signup-button.
Event names will be truncated past 50 characters.

​
How It Works

The tracker automatically:
  1. Listens for click events on all elements with the data-umami-event attribute
  2. Captures clicks on the element itself or its closest parent <a> or <button> element
  3. Sends the event name and any associated data to your Umami instance

​
Tracking Different Elements

Track button clicks:
<button data-umami-event="subscribe-newsletter">Subscribe</button>
<button data-umami-event="download-app">Download</button>
<button data-umami-event="play-video">Play Video</button>
The tracker intelligently handles navigation to ensure events are recorded: For internal links without target="_blank", the tracker:
  1. Prevents default navigation
  2. Sends the event to Umami
  3. Completes navigation after the event is tracked
<a href="/dashboard" data-umami-event="open-dashboard">Go to Dashboard</a>
For external links or links that open in new tabs, the tracker allows normal navigation: 
<a href="https://github.com" data-umami-event="visit-github" target="_blank">
  View on GitHub
</a>

​
Special Cases

The tracker also handles:
  • Command/Ctrl + Click (opens in new tab)
  • Shift + Click (opens in new window)
  • Middle mouse button clicks
  • Links with target="_top"

​
Event Naming Best Practices

1

Use descriptive names

Choose names that clearly describe the action:
<!-- Good -->
<button data-umami-event="subscribe-newsletter">Subscribe</button>
<button data-umami-event="download-whitepaper">Download</button>

<!-- Avoid -->
<button data-umami-event="button1">Subscribe</button>
<button data-umami-event="click">Download</button>
2

Use kebab-case

Separate words with hyphens for consistency:
<button data-umami-event="view-pricing-page">View Pricing</button>
3

Keep names concise

Remember that event names are truncated at 50 characters:
<!-- Good (32 characters) -->
<button data-umami-event="subscribe-monthly-newsletter">Subscribe</button>

<!-- Too long (will be truncated) -->
<button data-umami-event="subscribe-to-monthly-newsletter-for-product-updates">Subscribe</button>
4

Group related events

Use prefixes to group related events:
<button data-umami-event="cta-header-signup">Sign Up</button>
<button data-umami-event="cta-footer-signup">Sign Up</button>
<button data-umami-event="cta-modal-signup">Sign Up</button>

​
Adding Event Data

To attach additional data to your events, use the data-umami-event-* attributes: 
<button
  data-umami-event="purchase"
  data-umami-event-product="Pro Plan"
  data-umami-event-price="29.99"
>
  Buy Now
</button>

Learn More

Learn how to attach custom data to events →

​
Complete Examples

<button
  data-umami-event="add-to-cart"
  data-umami-event-product="Laptop"
  data-umami-event-category="Electronics"
  data-umami-event-price="999"
>
  Add to Cart
</button>

​
When to Use HTML vs JavaScript

Use HTML Attributes When

  • Tracking simple click events
  • Working with static HTML
  • You want declarative tracking
  • No dynamic data is needed

Use JavaScript API When

  • Tracking non-click events
  • Data comes from application state
  • Using frameworks like React
  • Need programmatic control

​
Next Steps

Custom Events

Track events programmatically using the JavaScript API

Event Data

Learn how to attach custom data to your events

Build docs developers (and LLMs) love

Get started for freeTalk to us