use-now

Reactive Unix timestamp in milliseconds.


Package	`@vizejs/composable/use-now`
Own the source	`vize lib pull composable:use-now`
Runtime exports	`useTimestamp`, `useNow`
Gzip budget	3072 B

Usage

import { useTimestamp, useNow } from "@vizejs/composable/use-now";

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`useTimestamp`	timing	experimental	deterministic-fallback	caller-managed	caller, reactive-scope	web, server, worker, native, desktop, terminal	`globalThis`, `window`	`useIntervalFn`, `useRafFn`
`useNow`	timing	experimental	deterministic-fallback	caller-managed	caller, reactive-scope	web, server, worker, native, desktop, terminal	`globalThis`, `window`	`useIntervalFn`, `useRafFn`

API

`useTimestamp`

Reactive Unix timestamp in milliseconds. Updates on a millisecond interval or every animation frame. For SSR, supply UseTimestampOptions.initial (or an injected now) so the server and the hydrating client render the same value; no timer runs on the server. Timers stop with the owning reactive scope.

function useTimestamp(options?: UseTimestampOptions<false>): Readonly<ShallowRef<number>>

const timestamp = useTimestamp({ interval: 250 });
const { timestamp: t, pause } = useTimestamp({ controls: true });

`useTimestamp`

function useTimestamp(options: UseTimestampOptions<true>): TimestampControls

`useTimestamp`

function useTimestamp( options: UseTimestampOptions<boolean> = {}, ): Readonly<ShallowRef<number>> | TimestampControls

`useNow`

Reactive current Date. Same cadence, SSR, and cleanup rules as useTimestamp; the value is a fresh Date derived from the latest timestamp.

function useNow(options?: UseNowOptions<false>): ComputedRef<Date>

const now = useNow({ initial: serverRenderedAt });

`useNow`

function useNow(options: UseNowOptions<true>): NowControls

`useNow`

function useNow(options: UseNowOptions<boolean> = {}): ComputedRef<Date> | NowControls

Types

`UseTimestampOptions`

Options for useTimestamp.

Member	Type	Description
`interval`?	`MaybeRefOrGetter<number> \| "requestAnimationFrame"`	Update cadence: a period in milliseconds (reactive), or `"requestAnimationFrame"` to update on every animation frame.
`offset`?	`number`	Milliseconds added to every reading, for example a server clock skew.
`now`?	`() => number`	Clock source returning Unix epoch milliseconds.
`initial`?	`number`	Hydration-stable starting value. When set, the first reading is this value on both server and client instead of the live clock, and the live clock takes over on the first tick. Pass the server's render time here (for example through a payload) to avoid hydration mismatches.
`immediate`?	`boolean`	Start updating as soon as the composable is created.
`runOnServer`?	`boolean`	Starts host timers or frames when no browser `window` is available.
`scheduler`?	`IntervalScheduler`	Repeating timer host for millisecond cadences.
`frameScheduler`?	`FrameScheduler`	Frame host for the `"requestAnimationFrame"` cadence.
`callback`?	`(timestamp: number) => void`	Invoked after every update with the new timestamp.
`controls`?	`Controls`	Return the full control object instead of the bare ref.

`TimestampControls`

Timestamp and controls returned by useTimestamp({ controls: true }).

Member	Type	Description
`isActive`	`Readonly<ShallowRef<boolean>>`	Whether the timer is logically running. On the server (without `runOnServer`) this reflects the requested state without starting a host timer, so server and client render the same initial value.
`pause`	`() => void`	Stop ticking. Idempotent.
`resume`	`() => void`	Start (or keep) ticking. Idempotent.
`timestamp`	`Readonly<ShallowRef<number>>`	Latest reading in Unix epoch milliseconds.
`refresh`	`() => number`	Read the clock immediately, store the value, and return it.

`NowControls`

Date and controls returned by useNow({ controls: true }).

Member	Type	Description
`isActive`	`Readonly<ShallowRef<boolean>>`	Whether the timer is logically running. On the server (without `runOnServer`) this reflects the requested state without starting a host timer, so server and client render the same initial value.
`pause`	`() => void`	Stop ticking. Idempotent.
`resume`	`() => void`	Start (or keep) ticking. Idempotent.
`now`	`ComputedRef<Date>`	Latest reading as a `Date`; a fresh instance per update.
`refresh`	`() => Date`	Read the clock immediately, store the value, and return it.