use-interval

Call a function on a fixed, pausable interval.


Package	`@vizejs/composable/use-interval`
Own the source	`vize lib pull composable:use-interval`
Runtime exports	`useIntervalFn`, `useInterval`
Gzip budget	2048 B

Usage

import { useIntervalFn, useInterval } from "@vizejs/composable/use-interval";

Runtime contract

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

API

`useIntervalFn`

Call a function on a fixed, pausable interval. intervalMs is reactive: while active, a change replaces the running timer with one using the new period. The timer is cleared when the owning reactive scope stops; call inside an active scope, or call pause() yourself. Server rendering is hydration-stable: without a browser window (and with UseIntervalFnOptions.runOnServer disabled) isActive reports the requested state but no host timer is created, so nothing leaks and the server snapshot matches the client's initial render.

function useIntervalFn( callback: () => void, intervalMs: MaybeRefOrGetter<number>, options: UseIntervalFnOptions = {}, ): PausableControls

const { pause, resume, isActive } = useIntervalFn(() => poll(), 5_000);

`useInterval`

Count interval ticks reactively. A thin wrapper over useIntervalFn whose state is a counter. Pass { controls: true } to receive pause/resume/reset alongside the counter; the return type follows the literal flag.

function useInterval( intervalMs?: MaybeRefOrGetter<number>, options?: UseIntervalOptions<false>, ): Readonly<ShallowRef<number>>

const ticks = useInterval(1_000); // Readonly<ShallowRef<number>>
const { counter, pause, reset } = useInterval(1_000, { controls: true });

`useInterval`

function useInterval( intervalMs: MaybeRefOrGetter<number>, options: UseIntervalOptions<true>, ): IntervalControls

`useInterval`

function useInterval( intervalMs: MaybeRefOrGetter<number> = 1_000, options: UseIntervalOptions<boolean> = {}, ): Readonly<ShallowRef<number>> | IntervalControls

Types

`IntervalScheduler`

Repeating timer host used by useIntervalFn and the clocks built on it. Implement this interface to integrate a deterministic test clock, a native runtime timer, or an application-owned scheduler. Handles are opaque: they are only handed back to IntervalScheduler.clearInterval.

Member	Type	Description
`setInterval`	`(callback: () => void, intervalMs: number) => unknown`	Starts a repeating callback and returns its opaque cancellation handle.
`clearInterval`	`(handle: unknown) => void`	Cancels a handle previously returned by `IntervalScheduler.setInterval`.

`PausableControls`

Pause/resume controls shared by the repeating timing composables.

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.

`UseIntervalFnOptions`

Options for useIntervalFn.

Member	Type	Description
`immediate`?	`boolean`	Start ticking as soon as the composable is created.
`immediateCallback`?	`boolean`	Invoke the callback synchronously whenever the timer (re)starts, in addition to every tick.
`runOnServer`?	`boolean`	Starts host timers when no browser `window` is available. Keep this disabled during server rendering: the controls then track the requested state but never schedule work. Enable it for native, desktop, worker, and test runtimes whose scheduler is lifecycle-bound.
`scheduler`?	`IntervalScheduler`	Owns the repeating timer.

`UseIntervalOptions`

Options for useInterval.

Member	Type	Description
`immediate`?	`boolean`	Start ticking as soon as the composable is created.
`immediateCallback`?	`boolean`	Invoke the callback synchronously whenever the timer (re)starts, in addition to every tick.
`runOnServer`?	`boolean`	Starts host timers when no browser `window` is available. Keep this disabled during server rendering: the controls then track the requested state but never schedule work. Enable it for native, desktop, worker, and test runtimes whose scheduler is lifecycle-bound.
`scheduler`?	`IntervalScheduler`	Owns the repeating timer.
`controls`?	`Controls`	Return the full control object instead of the bare counter ref.
`callback`?	`(count: number) => void`	Invoked after every increment with the new count.

`IntervalControls`

Counter and controls returned by useInterval(ms, { 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.
`counter`	`Readonly<ShallowRef<number>>`	Number of ticks since creation or the last `IntervalControls.reset`.
`reset`	`() => void`	Reset the counter to zero without touching the timer.