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

Minimal setup

Use a Vue 3.5+ project with Vue SFC compilation configured (see Vite+ integration).

vp install @vizejs/composable

Import the entry directly. Call lifecycle-bound utilities inside <script setup> so cleanup follows the component scope; consult the runtime contract for this entry's SSR and hydration behavior.

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

Try it

Show a live clock

Render the current time and update it on an interval that can be paused.

Open the interactive example

What to observe: The clock ticks every second. Pause clock stops it; Resume clock continues from the current time.

Pass controls: true to receive pause, resume and isActive with the date. initial gives server rendering and hydration the same first value; the interval then takes over in the browser.

Compare the initial and interacted states

Show a live clock: initial state — Initial state

Show a live clock: state after the verified interactions — After the verified interactions

Copy the example

Save this complete SFC in your Vue project. Its public imports and source are the same ones executed in the preview.

<script setup lang="ts">
import { computed } from "vue";
import { useNow } from "@vizejs/composable/use-now";

const { now, pause, resume, isActive } = useNow({ controls: true, interval: 1000, initial: 0 });
const clock = computed(() => now.value.toISOString().slice(11, 19));
</script>

<template>
  <div class="composable-example">
    <p>Show a live clock that updates every second and can be paused.</p>
    <output aria-live="off">{{ clock }} UTC</output>
    <button type="button" @click="() => (isActive ? pause() : resume())">
      {{ isActive ? "Pause clock" : "Resume clock" }}
    </button>
  </div>
</template>

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.