use-interval

Call a function on a fixed, pausable interval.

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 { useIntervalFn, useInterval } from "@vizejs/composable/use-interval";

Try it

Time a draft review

Track a review session with a pausable one-second clock and a reset control.

Open the interactive example

What to observe: Start the timer, wait for its count to rise, then pause. Paused time does not count. Reset changes the count without changing whether the timer is running.

With controls: true, useInterval returns counter, pause/resume, and reset. immediate: false gives SSR and the first client render the same paused zero state. The component scope owns and clears the real interval; this is a tick counter, not an elapsed wall-clock measurement.

Compare the initial and interacted states

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 { useInterval } from "@vizejs/composable/use-interval";

const { counter, isActive, pause, resume, reset } = useInterval(1000, {
  controls: true,
  immediate: false,
});
</script>

<template>
  <div class="composable-example">
    <p>Keep track of time spent reviewing a draft.</p>
    <output aria-live="polite"
      >{{ counter }} {{ counter === 1 ? "second" : "seconds" }} of review time</output
    >
    <p>{{ isActive ? "Review timer is running." : "Review timer is paused." }}</p>
    <div class="example-actions">
      <button type="button" :disabled="isActive" @click="resume">Start review timer</button>
      <button type="button" :disabled="!isActive" @click="pause">Pause review timer</button>
      <button type="button" @click="reset">Reset review time</button>
    </div>
  </div>
</template>

Runtime contract

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.

PausableControls

Pause/resume controls shared by the repeating timing composables.

UseIntervalFnOptions

Options for useIntervalFn.

UseIntervalOptions

Options for useInterval.

IntervalControls

Counter and controls returned by useInterval(ms, { controls: true }).