What is performance.mark()?
performance.mark() is a method defined in the W3C User Timing specification that creates a named PerformanceMark object representing a high-resolution timestamp marker in the browser's performance timeline. The method is available on the Performance interface, which is globally accessible via window.performance in browsers and via self.performance in Web Workers.
The core purpose of performance.mark() is to allow developers to mark specific moments in their application's execution flow. These marks serve as reference points that can later be analyzed to understand timing relationships between different parts of the application. For example, a developer might mark the moment a user clicks a button, when data fetching begins, and when the data is fully rendered, enabling precise measurement of user-perceived latency at each stage.
The PerformanceMark objects created by performance.mark() are automatically added to the Performance Timeline, a unified mechanism that browsers use to record various performance-related events. This integration means that custom marks created by the application coexist with browser-generated entries such as navigation timing, resource loading, and paint metrics, providing a comprehensive view of application performance.
Understanding performance.mark() is particularly valuable because it addresses a fundamental limitation of traditional JavaScript timing approaches. While developers have long used Date.now() or new Date().getTime() for basic timing, these methods only provide millisecond-level accuracy and can be affected by system clock adjustments. The Performance API, in contrast, uses monotonically increasing high-resolution time that isn't affected by clock changes, ensuring consistent and reliable measurements. For a deeper dive into timing APIs, see our User Timing API guide and learn how performance.measure() complements mark-based timing for duration calculations.
Syntax and Parameters
The performance.mark() method supports two calling patterns:
Basic Syntax
performance.mark(name)
Extended Syntax with Options
performance.mark(name, markOptions)
Parameters
name: A DOMString representing the name of the mark. This name serves as an identifier that can be used to reference the mark later.
markOptions (optional): An object with two properties:
- detail: Arbitrary metadata to include with the mark (default: null)
- startTime: The precise timestamp to use for the mark (default: performance.now())
Return Value
Returns the PerformanceMark object that was created, which includes:
- name: The mark's name
- entryType: Always 'mark'
- startTime: The timestamp
- duration: Always 0 (marks represent instantaneous points)
- detail: Any metadata provided
1// Create a basic timing mark2performance.mark('fetch-data-start');3 4// Perform an async operation5fetch('/api/data')6 .then(response => response.json())7 .then(data => {8 performance.mark('fetch-data-end');9 10 // Calculate the duration between marks11 performance.measure('fetch-duration', 'fetch-data-start', 'fetch-data-end');12 13 // Retrieve the measure14 const measures = performance.getEntriesByType('measure');15 console.log(`Fetch took: ${measures[0].duration}ms`);16 });Understanding what makes the User Timing API essential for performance measurement
High-Resolution Timestamps
Provides microsecond-level precision, far more accurate than Date.now() which only offers millisecond resolution
Monotonic Time Source
Uses monotonically increasing time that isn't affected by system clock adjustments, ensuring reliable measurements
Performance Timeline Integration
Marks automatically appear in the Performance Timeline alongside navigation timing, resource timing, and paint metrics
Metadata Support
The detail property allows attaching arbitrary structured data to marks for rich contextual information
Chrome DevTools Visualization
Custom marks can appear as dedicated tracks in Chrome's Performance panel when using the extensibility API
Cross-Browser Support
Standardized by W3C with broad support across all modern browsers including IE10+ and Web Workers
1performance.mark('custom-event', {2 detail: {3 devtools: {4 dataType: 'marker', // Required: identifies as a marker5 color: 'secondary', // 'primary', 'secondary', or 'tertiary'6 properties: [7 ['Component', 'ProductGrid'],8 ['Action', 'FilterChange']9 ],10 tooltipText: 'Product grid filtered'11 }12 }13});| Method | Description | Example |
|---|---|---|
| getEntriesByType(type) | Returns all entries of specified type | performance.getEntriesByType('mark') |
| getEntriesByName(name) | Returns all entries with specified name | performance.getEntriesByName('fetch-start') |
| getEntries() | Returns all performance entries | performance.getEntries() |
| clearMarks(name) | Removes marks from buffer | performance.clearMarks('old-mark') |
| clearMeasures(name) | Removes measures from buffer | performance.clearMeasures() |
| setResourceTimingBufferSize(n) | Sets resource timing buffer size | performance.setResourceTimingBufferSize(500) |
Frequently Asked Questions
Core Web Vitals
Learn about Google's essential metrics for measuring user experience: LCP, FID, and CLS.
Learn morePerformance Timeline API
Understand the comprehensive Performance API for measuring navigation, resource, and user timing.
Learn moreResource Timing API
Measure network performance for resources including images, scripts, and stylesheets.
Learn more