Umami allows you to attach custom data to events, providing deeper insights into user behavior. Event data can be added using HTML attributes or the JavaScript API.
Adding Data with HTML Attributes Attach custom data to events using data-umami-event-* attributes:
< button data-umami-event = "purchase" data-umami-event-product = "Pro Plan" data-umami-event-price = "29.99" data-umami-event-currency = "USD" > Buy Now </ button >
The tracker automatically extracts all attributes matching the pattern data-umami-event-* and includes them in the event payload.
How It Works When you click the button above, the tracker:
Finds the data-umami-event attribute (event name: purchase)
Scans for all data-umami-event-* attributes
Extracts the property name from each attribute (e.g., data-umami-event-product → product)
Creates an event data object:
{ name : 'purchase' , data : { product : 'Pro Plan' , price : '29.99' , currency : 'USD' } }
The regex pattern used to match attributes is /data-umami-event-([\w-_]+)/. Property names can contain letters, numbers, hyphens, and underscores.
Adding Data with JavaScript Pass an object as the second parameter to umami.track():
umami . track ( 'purchase' , { product: 'Pro Plan' , price: 29.99 , currency: 'USD' , quantity: 1 });
Data Structure Event data accepts any JSON-compatible structure:
interface EventData { [ key : string ] : number | string | EventData | number [] | string [] | EventData []; }
Supported Data Types Strings
Numbers
Arrays
Objects
umami . track ( 'event' , { name: 'John Doe' , email: '[email protected] ' , plan: 'premium' });
Strings have a maximum length of 500 characters and will be truncated if longer.
umami . track ( 'event' , { price: 29.99 , quantity: 3 , discount: 0.15 });
Numbers have a maximum precision of 4 decimal places .
umami . track ( 'event' , { tags: [ 'tech' , 'news' , 'update' ], scores: [ 95 , 87 , 92 ], items: [ { id: 1 , name: 'Item 1' }, { id: 2 , name: 'Item 2' } ] });
String arrays are converted to strings with a maximum length of 500 characters .
umami . track ( 'event' , { user: { id: 123 , name: 'John Doe' , preferences: { theme: 'dark' , notifications: true } } });
Objects have a maximum of 50 properties . Arrays are counted as 1 property.
Data Limitations To maintain performance, Umami enforces these limits on event data:
Type Limitation Behavior Strings Max 500 characters Truncated Numbers Max 4 decimal places Rounded Objects Max 50 properties Excess ignored Arrays Converted to string Max 500 characters
Data exceeding these limits will be automatically truncated or modified. Plan your event structure accordingly.
Common Data Patterns E-commerce Events Product View
Add to Cart
Purchase
umami . track ( 'product-view' , { product_id: 'SKU-12345' , product_name: 'Wireless Headphones' , category: 'Electronics' , price: 79.99 , currency: 'USD' , in_stock: true });
User Interactions Form Submission
Video Interaction
Search
umami . track ( 'form-submit' , { form_name: 'contact' , form_type: 'support' , fields_filled: 5 , time_spent: 45 });
Feature Usage Feature Activation
Export Action
Integration
umami . track ( 'feature-enabled' , { feature_name: 'dark_mode' , user_type: 'premium' , enabled_from: 'settings' , first_time: true });
HTML Attribute Examples E-commerce Button
Download Link
Social Share
CTA Button
< button data-umami-event = "add-to-cart" data-umami-event-product-id = "SKU-12345" data-umami-event-product-name = "Wireless Headphones" data-umami-event-price = "79.99" data-umami-event-quantity = "1" > Add to Cart </ button >
Best Practices
Use consistent naming
Choose a naming convention and stick to it: // Good - snake_case umami . track ( 'event' , { user_id: 123 , product_name: 'Item' , cart_total: 99.99 }); // Good - camelCase umami . track ( 'event' , { userId: 123 , productName: 'Item' , cartTotal: 99.99 });
Keep data relevant
Only include data you’ll actually use for analysis: // Good - focused data umami . track ( 'signup' , { plan: 'premium' , referral_source: 'google' }); // Avoid - unnecessary data umami . track ( 'signup' , { plan: 'premium' , browser_plugins: [ ... ], screen_resolution: '1920x1080' , timezone: 'UTC-5' // Already tracked automatically });
Mind the limits
Stay within data constraints: // Good - concise strings umami . track ( 'event' , { description: 'User completed checkout' }); // Avoid - very long strings umami . track ( 'event' , { description: 'Very long description that exceeds 500 characters...' // Will be truncated });
Structure nested data carefully
Remember the 50 property limit: // Good - within limits umami . track ( 'event' , { order: { id: 123 , total: 99.99 , items: [ ... ] // Counts as 1 property } }); // Avoid - too many properties umami . track ( 'event' , { prop1: 1 , prop2: 2 , /* ... */ prop51: 51 // Properties beyond 50 will be ignored });
For complex data that exceeds limits, consider tracking multiple events or summarizing the data before sending.
Next Steps
Tracker Functions Explore all available tracker functions
User Identification Learn how to identify and track users