I love using Umami Analytics — it’s privacy-friendly, fast, and self-hostable. But I found myself repeatedly wiring up the same event tracking logic for things like scroll depth, time on page, and click tracking.
So I built umami-kit: a drop-in JavaScript utility that adds rich, configurable analytics to any Umami-powered site — with minimal effort and no cookies.
🚀 What It Tracks Automatically
Once added to your site, umami-kit can track:
- ✅ Scroll depth (customizable thresholds)
- ✅ Time on page with heartbeat & idle detection
- ✅ Clicks (either explicitly marked or all clickable elements)
- ✅ Element visibility (track when key content enters viewport)
- ✅ External link clicks
- ✅ Page exit stats (total time, max scroll)
- ✅ And more, including forms, downloads, searches, and ecommerce events via the programmatic API
🛠 How to Use It
Drop-in setup using HTML attributes:
<!-- Include your Umami instance script -->
<script async src="https://analytics.yoursite.com/script.js" data-website-id="your-site-id"></script>
<!-- Load umami-kit -->
<script defer src="/path/to/umami-kit.js"></script>
<!-- Auto-track with config -->
<body
data-umami-auto-track
data-umami-auto-track-all-clicks="true"
data-umami-scroll-thresholds="25,50,75,90"
data-umami-heartbeat="30000"
data-umami-debug="true">
Or initialize manually for full control:
const kit = new UmamiKit({
autoTrackAllClicks: true,
scrollDepthThresholds: [25, 50, 75, 90],
heartbeatInterval: 30000,
debug: true
});
You can also track visibility and clicks declaratively:
<!-- Track CTA button -->
<button data-umami-track="subscribe-click">Subscribe</button>
<!-- Track when element becomes visible -->
<section data-umami-visible="pricing-visible"> ... </section>
🧪 How I Use It
I self-host Umami on Vercel, using a custom subdomain per site for clean, first-party analytics. umami-kit builds on that by collecting richer behavioral data without any cookies, third-party requests, or PII.
This lets me understand how people engage with my sites while maintaining full respect for user privacy — something Google Analytics has never made easy.
🔗 Check it out on GitHub:
https://github.com/rhelmer/umami-kit
💡 Let me know what you think — feedback, PRs, and suggestions are welcome.