use-timeout

Call a function once after a delay, with restart and cancel controls.


Package	`@vizejs/composable/use-timeout`
Own the source	`vize lib pull composable:use-timeout`
Runtime exports	`useTimeoutFn`, `useTimeout`
Gzip budget	1280 B

Usage

import { useTimeoutFn, useTimeout } from "@vizejs/composable/use-timeout";

Runtime contract

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

API

`useTimeoutFn`

Call a function once after a delay, with restart and cancel controls. The typing is arity-aware: a zero-argument callback may start immediately, while a callback with parameters requires { immediate: false } so it can only ever run with arguments supplied to start(...). delayMs is reactive and read on every start. Server rendering is hydration-stable: without a browser window (and with UseTimeoutFnOptions.runOnServer disabled) isPending reports the requested state but no timer is created. A pending timer is cleared when the owning reactive scope stops.

function useTimeoutFn( callback: () => void, delayMs: MaybeRefOrGetter<number>, options?: UseTimeoutFnOptions, ): TimeoutFnControls<[]>

const { start, stop } = useTimeoutFn((id: string) => save(id), 500, { immediate: false });
start("draft-1");

`useTimeoutFn`

function useTimeoutFn<Args extends readonly unknown[]>( callback: (...args: Args) => void, delayMs: MaybeRefOrGetter<number>, options: UseTimeoutFnOptions & { readonly immediate: false }, ): TimeoutFnControls<Args>

`useTimeoutFn`

function useTimeoutFn( callback: (...args: readonly unknown[]) => void, delayMs: MaybeRefOrGetter<number>, options: UseTimeoutFnOptions = {}, ): TimeoutFnControls<readonly unknown[]>

`useTimeout`

Reactive "has the delay elapsed yet?" flag. A wrapper over useTimeoutFn. Pass { controls: true } to receive start/stop alongside the flag; the return type follows the literal flag. Stopping a pending timer marks it ready.

function useTimeout( delayMs?: MaybeRefOrGetter<number>, options?: UseTimeoutOptions<false>, ): ComputedRef<boolean>

const ready = useTimeout(300); // ComputedRef<boolean>
const { ready: done, start } = useTimeout(300, { controls: true, immediate: false });

`useTimeout`

function useTimeout( delayMs: MaybeRefOrGetter<number>, options: UseTimeoutOptions<true>, ): TimeoutControls

`useTimeout`

function useTimeout( delayMs: MaybeRefOrGetter<number> = 1_000, options: UseTimeoutOptions<boolean> = {}, ): ComputedRef<boolean> | TimeoutControls

Types

`UseTimeoutFnOptions`

Options for useTimeoutFn.

Member	Type	Description
`immediate`?	`boolean`	Start the timer as soon as the composable is created. Only available for callbacks without arguments; pass `false` to schedule a callback that takes arguments through `TimeoutFnControls.start`.
`runOnServer`?	`boolean`	Starts host timers when no browser `window` is available. Keep this disabled during server rendering: `isPending` then reports the requested state but no timer is created and the callback never runs.
`scheduler`?	`TimeoutScheduler`	Owns the single-shot timer.

`TimeoutFnControls`

Controls returned by useTimeoutFn.

Member	Type	Description
`isPending`	`Readonly<ShallowRef<boolean>>`	Whether a call is scheduled and has not fired or been stopped yet.
`start`	`(...args: Args) => void`	(Re)start the timer. A pending call is replaced, and the callback later receives exactly these arguments.
`stop`	`() => boolean`	Cancel the pending call.

`UseTimeoutOptions`

Options for useTimeout.

Member	Type	Description
`immediate`?	`boolean`	Start the timer as soon as the composable is created. Only available for callbacks without arguments; pass `false` to schedule a callback that takes arguments through `TimeoutFnControls.start`.
`runOnServer`?	`boolean`	Starts host timers when no browser `window` is available. Keep this disabled during server rendering: `isPending` then reports the requested state but no timer is created and the callback never runs.
`scheduler`?	`TimeoutScheduler`	Owns the single-shot timer.
`controls`?	`Controls`	Return the full control object instead of the bare readiness ref.
`callback`?	`() => void`	Invoked when the timeout elapses.

`TimeoutControls`

Readiness and controls returned by useTimeout(ms, { controls: true }).

Member	Type	Description
`isPending`	`Readonly<ShallowRef<boolean>>`	Whether a call is scheduled and has not fired or been stopped yet.
`start`	`(...args: Args) => void`	(Re)start the timer. A pending call is replaced, and the callback later receives exactly these arguments.
`stop`	`() => boolean`	Cancel the pending call.
`ready`	`ComputedRef<boolean>`	`true` once the timer elapsed or was stopped, `false` while pending.