use-performance-observer

Observe performance entries with callbacks typed by entry type.


Package	`@vizejs/composable/use-performance-observer`
Own the source	`vize lib pull composable:use-performance-observer`
Runtime exports	`usePerformanceObserver`
Gzip budget	2304 B

Usage

import { usePerformanceObserver } from "@vizejs/composable/use-performance-observer";

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`usePerformanceObserver`	performance	experimental	deterministic-fallback	caller-managed	caller, reactive-scope	web, desktop	`window`	`tryOnScopeDispose`

API

`usePerformanceObserver`

Observe performance entries with callbacks typed by entry type. Each supported type is observed with its own observe({ type }) call so buffered and durationThreshold apply. Types missing from PerformanceObserver.supportedEntryTypes are skipped; supported is false when none remain. The observer follows reactive entryTypes and is disconnected when the owning reactive scope stops; outside a scope the caller owns stop(). Server rendering: no observer is created and supported is false. Inside a component the observer connects after mounting, so hydration renders the server state first.

function usePerformanceObserver<const Type extends PerformanceEntryType>( entryTypes: MaybeRefOrGetter<Type | readonly Type[]>, callback: PerformanceObserverCallback<Type>, options: UsePerformanceObserverOptions = {}, ): PerformanceObserverControls<Type>

usePerformanceObserver("largest-contentful-paint", (entries) => {
  console.log(entries.at(-1)?.renderTime);
}, { buffered: true });

Types

`PerformanceEntryLike`

Fields shared by every performance entry consumed by usePerformanceObserver.

Member	Type	Description
`name`	`string`	Entry name (URL, mark name, paint name, event type, …).
`entryType`	`string`	Entry type this entry was reported for.
`startTime`	`number`	Start time relative to the time origin, in milliseconds.
`duration`	`number`	Duration in milliseconds (`0` for instantaneous entries).

`LargestContentfulPaintEntryLike`

largest-contentful-paint entry.

Member	Type	Description
`name`	`string`	Entry name (URL, mark name, paint name, event type, …).
`entryType`	`string \| "largest-contentful-paint"`	Entry type this entry was reported for.
`startTime`	`number`	Start time relative to the time origin, in milliseconds.
`duration`	`number`	Duration in milliseconds (`0` for instantaneous entries).
`renderTime`	`number`	Render time, or `0` for cross-origin images without Timing-Allow-Origin.
`loadTime`	`number`	Load time of the resource, or `0` for text.
`size`	`number`	Visible area of the element in square pixels.
`id`	`string`	Element `id`, or an empty string.
`url`	`string`	Image URL, or an empty string for text.

`LayoutShiftEntryLike`

layout-shift entry (Layout Instability API).

Member	Type	Description
`name`	`string`	Entry name (URL, mark name, paint name, event type, …).
`entryType`	`string \| "layout-shift"`	Entry type this entry was reported for.
`startTime`	`number`	Start time relative to the time origin, in milliseconds.
`duration`	`number`	Duration in milliseconds (`0` for instantaneous entries).
`value`	`number`	Layout shift score.
`hadRecentInput`	`boolean`	Whether a user input happened within the previous 500 ms.
`lastInputTime`	`number`	Time of the most recent input.

`EventTimingFieldsLike`

Fields of Event Timing entries (event and first-input).

Member	Type	Description
`name`	`string`	Entry name (URL, mark name, paint name, event type, …).
`entryType`	`string`	Entry type this entry was reported for.
`startTime`	`number`	Start time relative to the time origin, in milliseconds.
`duration`	`number`	Duration in milliseconds (`0` for instantaneous entries).
`processingStart`	`number`	Time the event handlers started running.
`processingEnd`	`number`	Time the event handlers finished running.
`cancelable`	`boolean`	Whether the event was cancelable.
`interactionId`?	`number`	Interaction identifier; `0` when the event is not part of an interaction.

`EventTimingEntryLike`

event entry (Event Timing API).

Member	Type	Description
`name`	`string`	Entry name (URL, mark name, paint name, event type, …).
`entryType`	`string \| "event"`	Entry type this entry was reported for.
`startTime`	`number`	Start time relative to the time origin, in milliseconds.
`duration`	`number`	Duration in milliseconds (`0` for instantaneous entries).
`processingStart`	`number`	Time the event handlers started running.
`processingEnd`	`number`	Time the event handlers finished running.
`cancelable`	`boolean`	Whether the event was cancelable.
`interactionId`?	`number`	Interaction identifier; `0` when the event is not part of an interaction.

`FirstInputEntryLike`

first-input entry (Event Timing API).

Member	Type	Description
`name`	`string`	Entry name (URL, mark name, paint name, event type, …).
`entryType`	`string \| "first-input"`	Entry type this entry was reported for.
`startTime`	`number`	Start time relative to the time origin, in milliseconds.
`duration`	`number`	Duration in milliseconds (`0` for instantaneous entries).
`processingStart`	`number`	Time the event handlers started running.
`processingEnd`	`number`	Time the event handlers finished running.
`cancelable`	`boolean`	Whether the event was cancelable.
`interactionId`?	`number`	Interaction identifier; `0` when the event is not part of an interaction.

`PaintEntryLike`

paint entry (first-paint or first-contentful-paint).

Member	Type	Description
`name`	`string`	Entry name (URL, mark name, paint name, event type, …).
`entryType`	`string \| "paint"`	Entry type this entry was reported for.
`startTime`	`number`	Start time relative to the time origin, in milliseconds.
`duration`	`number`	Duration in milliseconds (`0` for instantaneous entries).

`ResourceTimingFieldsLike`

Fields shared by resource and navigation timing entries.

Member	Type	Description
`name`	`string`	Entry name (URL, mark name, paint name, event type, …).
`entryType`	`string`	Entry type this entry was reported for.
`startTime`	`number`	Start time relative to the time origin, in milliseconds.
`duration`	`number`	Duration in milliseconds (`0` for instantaneous entries).
`initiatorType`	`string`	Initiator (`navigation`, `script`, `img`, `fetch`, …).
`requestStart`	`number`	Time the request started.
`responseStart`	`number`	Time the first response byte arrived.
`responseEnd`	`number`	Time the last response byte arrived.
`transferSize`	`number`	Transferred size in bytes including headers.

`ResourceTimingEntryLike`

resource entry (Resource Timing API).

Member	Type	Description
`name`	`string`	Entry name (URL, mark name, paint name, event type, …).
`entryType`	`string \| "resource"`	Entry type this entry was reported for.
`startTime`	`number`	Start time relative to the time origin, in milliseconds.
`duration`	`number`	Duration in milliseconds (`0` for instantaneous entries).
`initiatorType`	`string`	Initiator (`navigation`, `script`, `img`, `fetch`, …).
`requestStart`	`number`	Time the request started.
`responseStart`	`number`	Time the first response byte arrived.
`responseEnd`	`number`	Time the last response byte arrived.
`transferSize`	`number`	Transferred size in bytes including headers.

`NavigationTimingEntryLike`

navigation entry (Navigation Timing API).

Member	Type	Description
`name`	`string`	Entry name (URL, mark name, paint name, event type, …).
`entryType`	`string \| "navigation"`	Entry type this entry was reported for.
`startTime`	`number`	Start time relative to the time origin, in milliseconds.
`duration`	`number`	Duration in milliseconds (`0` for instantaneous entries).
`initiatorType`	`string`	Initiator (`navigation`, `script`, `img`, `fetch`, …).
`requestStart`	`number`	Time the request started.
`responseStart`	`number`	Time the first response byte arrived.
`responseEnd`	`number`	Time the last response byte arrived.
`transferSize`	`number`	Transferred size in bytes including headers.
`type`	`string`	Navigation type (`navigate`, `reload`, `back_forward`, `prerender`).
`activationStart`?	`number`	Time a prerendered page was activated; `0` or absent otherwise.
`domContentLoadedEventEnd`	`number`	End of the `DOMContentLoaded` handlers.
`loadEventEnd`	`number`	End of the `load` handlers.

`LongTaskEntryLike`

longtask entry (Long Tasks API).

Member	Type	Description
`name`	`string`	Entry name (URL, mark name, paint name, event type, …).
`entryType`	`string \| "longtask"`	Entry type this entry was reported for.
`startTime`	`number`	Start time relative to the time origin, in milliseconds.
`duration`	`number`	Duration in milliseconds (`0` for instantaneous entries).

`MarkEntryLike`

mark entry (User Timing API).

Member	Type	Description
`name`	`string`	Entry name (URL, mark name, paint name, event type, …).
`entryType`	`string \| "mark"`	Entry type this entry was reported for.
`startTime`	`number`	Start time relative to the time origin, in milliseconds.
`duration`	`number`	Duration in milliseconds (`0` for instantaneous entries).
`detail`	`unknown`	Detail passed to `performance.mark`.

`MeasureEntryLike`

measure entry (User Timing API).

Member	Type	Description
`name`	`string`	Entry name (URL, mark name, paint name, event type, …).
`entryType`	`string \| "measure"`	Entry type this entry was reported for.
`startTime`	`number`	Start time relative to the time origin, in milliseconds.
`duration`	`number`	Duration in milliseconds (`0` for instantaneous entries).
`detail`	`unknown`	Detail passed to `performance.measure`.

`ElementTimingEntryLike`

element entry (Element Timing API).

Member	Type	Description
`name`	`string`	Entry name (URL, mark name, paint name, event type, …).
`entryType`	`string \| "element"`	Entry type this entry was reported for.
`startTime`	`number`	Start time relative to the time origin, in milliseconds.
`duration`	`number`	Duration in milliseconds (`0` for instantaneous entries).
`identifier`	`string`	Value of the `elementtiming` attribute.
`renderTime`	`number`	Render time.
`loadTime`	`number`	Load time of the resource, or `0` for text.
`id`	`string`	Element `id`, or an empty string.
`url`	`string`	Image URL, or an empty string for text.

`LongAnimationFrameEntryLike`

long-animation-frame entry (Long Animation Frames API).

Member	Type	Description
`name`	`string`	Entry name (URL, mark name, paint name, event type, …).
`entryType`	`string \| "long-animation-frame"`	Entry type this entry was reported for.
`startTime`	`number`	Start time relative to the time origin, in milliseconds.
`duration`	`number`	Duration in milliseconds (`0` for instantaneous entries).
`renderStart`	`number`	Start of the rendering phase.
`styleAndLayoutStart`	`number`	Start of style and layout.
`blockingDuration`	`number`	Total blocking time of the frame in milliseconds.
`firstUIEventTimestamp`	`number`	Time of the first UI event handled in this frame, or `0`.

`PerformanceEntryTypeMap`

Entry interface delivered for each supported entry type.

Member	Type	Description
`largest-contentful-paint`	`LargestContentfulPaintEntryLike`	Largest Contentful Paint candidates.
`layout-shift`	`LayoutShiftEntryLike`	Layout shifts.
`event`	`EventTimingEntryLike`	Event Timing entries.
`first-input`	`FirstInputEntryLike`	The first input of the page.
`paint`	`PaintEntryLike`	First paint and first contentful paint.
`navigation`	`NavigationTimingEntryLike`	Document navigation timing.
`resource`	`ResourceTimingEntryLike`	Resource timing.
`longtask`	`LongTaskEntryLike`	Tasks longer than 50 ms.
`mark`	`MarkEntryLike`	User Timing marks.
`measure`	`MeasureEntryLike`	User Timing measures.
`element`	`ElementTimingEntryLike`	Element Timing entries.
`long-animation-frame`	`LongAnimationFrameEntryLike`	Long animation frames.

`PerformanceObserveInit`

Options passed to PerformanceObserverLike.observe.

Member	Type	Description
`type`	`string`	Single entry type to observe.
`buffered`?	`boolean`	Replay entries buffered before observation started.
`durationThreshold`?	`number`	Minimum duration of reported `event` entries.

`PerformanceObserverEntryListLike`

Minimal entry list handed to observer callbacks.

Member	Type	Description
`getEntries`	`() => readonly PerformanceEntryLike[]`	Every entry of this batch.

`PerformanceObserverLike`

Minimal PerformanceObserver instance.

Member	Type	Description
`observe`	`(options: PerformanceObserveInit) => void`	Start observing one entry type.
`disconnect`	`() => void`	Stop observing everything.
`takeRecords`	`() => readonly PerformanceEntryLike[]`	Return and clear pending entries.

`PerformanceObserverHost`

Minimal PerformanceObserver constructor.

Member	Type	Description
`supportedEntryTypes`?	`readonly string[] \| undefined`	Entry types this runtime supports; every type is attempted when absent.

`UsePerformanceObserverOptions`

Options for usePerformanceObserver.

Member	Type	Description
`PerformanceObserver`?	`MaybeRef<PerformanceObserverHost \| null \| undefined>`	`PerformanceObserver` constructor for alternate runtimes and tests. A ref (not a getter) because the host itself is a constructor function.
`buffered`?	`boolean`	Replay entries recorded before observation started.
`durationThreshold`?	`number`	Minimum duration in milliseconds of reported `event` entries (the platform rounds it and clamps it to at least 16).
`immediate`?	`boolean`	Start observing immediately.

`PerformanceObserverControls`

Reactive state and actions returned by usePerformanceObserver.

Member	Type	Description
`supported`	`ComputedRef<boolean>`	Whether an observer exists and supports at least one requested type.
`observedTypes`	`ComputedRef<readonly Type[]>`	Requested entry types the runtime supports.
`isActive`	`Readonly<ShallowRef<boolean>>`	Whether an observer is currently connected.
`error`	`Readonly<ShallowRef<unknown>>`	Most recent failure thrown by `observe`, cleared on the next start.
`start`	`() => void`	Start (or restart) observing.
`stop`	`() => void`	Disconnect the observer. Repeated calls are safe.
`takeRecords`	`() => readonly PerformanceEntryTypeMap[Type][]`	Return and clear entries that are queued but not yet delivered.