use-countdown

Count down from a number of ticks to zero.


Package	`@vizejs/composable/use-countdown`
Own the source	`vize lib pull composable:use-countdown`
Runtime exports	`useCountdown`
Gzip budget	2560 B

Usage

import { useCountdown } from "@vizejs/composable/use-countdown";

Runtime contract

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

API

`useCountdown`

Count down from a number of ticks to zero. Builds on useIntervalFn: pause/resume keep the remaining count, start and reset restore it, and the timer pauses itself at zero after calling onComplete. The initial count is reactive only for later start()/reset() calls without an argument. Server rendering is hydration-stable (no timer, remaining stays at the initial count).

function useCountdown( initialCount: MaybeRefOrGetter<number>, options: UseCountdownOptions = {}, ): CountdownControls

const { remaining, start } = useCountdown(60, { onComplete: resendAvailable });
start();

Types

`UseCountdownOptions`

Options for useCountdown.

Member	Type	Description
`intervalMs`?	`MaybeRefOrGetter<number>`	Milliseconds between two decrements. Reactive.
`immediate`?	`boolean`	Start counting down as soon as the composable is created.
`onTick`?	`(remaining: number) => void`	Invoked after every decrement with the remaining count.
`onComplete`?	`() => void`	Invoked once when the count reaches zero.
`runOnServer`?	`boolean`	Starts host timers when no browser `window` is available.
`scheduler`?	`IntervalScheduler`	Repeating timer host.

`CountdownControls`

State and controls returned by useCountdown.

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.
`remaining`	`Readonly<ShallowRef<number>>`	Remaining whole ticks; never negative.
`isComplete`	`ComputedRef<boolean>`	Whether the countdown reached zero.
`start`	`(count?: number) => void`	Reset to `count` (default: the initial count) and start ticking.
`reset`	`(count?: number) => void`	Pause and reset to `count` (default: the initial count).
`stop`	`() => void`	Pause and jump to zero without firing `onComplete`.