Angular library for Umami Analytics - privacy-focused, lightweight analytics tracking
npm install ngx-umamiAngular library for Umami Analytics - a privacy-focused, lightweight analytics platform.


- 🚀 Easy Setup - Simple standalone configuration with provideUmami()
- 📊 Event Tracking - Track custom events with optional data payloads
- 🔄 Router Integration - Automatic page view tracking on route changes
- 🎯 Directive - Declarative event tracking with umamiTrack directive
- 🔒 Privacy First - Respects Do Not Track, GDPR compliant
- 🌐 SSR Compatible - Works with Angular Universal/SSR
- 📦 Tree-shakeable - Only includes what you use
| Angular Version | ngx-umami Version |
|-----------------|-------------------|
| 17.x - 21.x | 1.x |
``bashRecommended
pnpm add ngx-umami
> Note: We recommend using pnpm for faster installs and better disk space efficiency.
Quick Start
$3
`typescript
// app.config.ts
import { ApplicationConfig } from '@angular/core';
import { provideRouter } from '@angular/router';
import { provideUmami, withRouterTracking } from 'ngx-umami';export const appConfig: ApplicationConfig = {
providers: [
provideRouter(routes),
provideUmami({
websiteId: 'your-website-id',
src: 'https://analytics.yourdomain.com/script.js'
}),
// Optional: Enable automatic page view tracking on route changes
withRouterTracking()
]
};
`$3
`typescript
import { Component } from '@angular/core';
import { injectUmami } from 'ngx-umami';@Component({
selector: 'app-checkout',
template:
})
export class CheckoutComponent {
private umami = injectUmami(); onPurchase() {
this.umami.trackEvent('purchase', {
product: 'Premium Plan',
price: 99.99,
currency: 'USD'
});
}
}
`$3
`typescript
import { Component } from '@angular/core';
import { UmamiTrackDirective } from 'ngx-umami';@Component({
selector: 'app-signup',
standalone: true,
imports: [UmamiTrackDirective],
template:
umamiTrack="cta_click"
[umamiTrackData]="{ location: 'header', variant: 'blue' }">
Get Started
`
})
export class SignupComponent {}
`typescript
provideUmami({
// Required
websiteId: 'your-website-id', // From Umami dashboard
src: 'https://analytics.example.com/script.js', // Your Umami script URL
// Optional
enabled: true, // Enable/disable tracking (default: true)
autoTrack: true, // Auto track page views (default: true)
doNotTrack: false, // Honor browser DNT setting (default: false)
domains: ['example.com'], // Restrict to specific domains
tag: 'production', // Tag for filtering in dashboard
excludeSearch: false, // Exclude URL search params
excludeHash: false, // Exclude URL hash
hostUrl: 'https://proxy.example.com' // Custom data endpoint
})
`
#### trackPageView(payload?)
Track a page view manually.
`typescript
umami.trackPageView();
umami.trackPageView({
url: '/custom-page',
title: 'Custom Page Title',
referrer: 'https://google.com'
});
`
#### trackEvent(eventName, eventData?)
Track a custom event.
`typescript
// Simple event
umami.trackEvent('button_click');
// Event with data (max 50 properties)
umami.trackEvent('form_submit', {
formName: 'contact',
fields: 5,
hasAttachment: true
});
`
#### identify(sessionIdOrData, sessionData?)
Identify user sessions.
`typescript
// With session ID
umami.identify('user-123');
// With session ID and data
umami.identify('user-123', {
plan: 'premium',
role: 'admin'
});
// With data only
umami.identify({
plan: 'premium',
signupDate: '2024-01-15'
});
`
#### isAvailable()
Check if tracking is available.
`typescript`
if (umami.isAvailable()) {
umami.trackEvent('ready');
}
#### disable()
Disable tracking programmatically.
`typescript`
umami.disable();
Declarative event tracking on DOM elements.
`html
umamiTrack="download"
[umamiTrackData]="{ file: 'report.pdf', size: 1024 }">
Download
umamiTrack="search_focus"
umamiTrackOn="focus"
placeholder="Search...">
Supported events:
click, focus, blur, mouseenter, mouseleave, submit$3
Enable automatic page view tracking on Angular router navigation.
`typescript
// app.config.ts
providers: [
provideRouter(routes),
provideUmami({
websiteId: 'xxx',
src: 'https://...',
autoTrack: false // Disable Umami's auto-track since router handles it
}),
withRouterTracking()
]
`$3
Configure Umami using a factory function with dependency injection.
`typescript
import { provideUmamiWithFactory } from 'ngx-umami';
import { ConfigService } from './config.service';providers: [
provideUmamiWithFactory(
(config: ConfigService) => ({
websiteId: config.umamiWebsiteId,
src: config.umamiSrc,
enabled: config.isProduction
}),
[ConfigService]
)
]
`Environment-based Configuration
`typescript
// environments/environment.ts
export const environment = {
production: false,
umami: {
websiteId: 'dev-website-id',
src: 'https://analytics.example.com/script.js',
enabled: false // Disable in development
}
};// environments/environment.prod.ts
export const environment = {
production: true,
umami: {
websiteId: 'prod-website-id',
src: 'https://analytics.example.com/script.js',
enabled: true
}
};
// app.config.ts
import { environment } from './environments/environment';
providers: [
provideUmami(environment.umami)
]
``The library automatically handles server-side rendering. Tracking is only active in the browser environment - no configuration needed.
MIT