use-timeout

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

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 { useTimeoutFn, useTimeout } from "@vizejs/composable/use-timeout";

Try it

Schedule a review reminder

Schedule one delayed action, replace its deadline, or cancel it before it runs.

Open the interactive example

What to observe: Schedule a reminder and cancel it before one second passes. Its delivered count stays unchanged. Schedule again to see the callback run once. Scheduling while pending restarts the one-second deadline.

This entry exports useTimeoutFn as well as useTimeout. The example uses useTimeoutFn with immediate: false; no timer starts during SSR. Pending state belongs to the composable, while the callback owns the message and delivery count. Unmounting clears a pending timer.

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 { ref } from "vue";
import { useTimeoutFn } from "@vizejs/composable/use-timeout";

const reminders = ref(0);
const message = ref("No reminder scheduled.");
const { isPending, start, stop } = useTimeoutFn(
  () => {
    reminders.value += 1;
    message.value = "Reminder delivered.";
  },
  1000,
  { immediate: false },
);

function scheduleReminder(): void {
  message.value = "Reminder scheduled for one second from now.";
  start();
}

function cancelReminder(): void {
  if (stop()) message.value = "Reminder canceled.";
}
</script>

<template>
  <div class="composable-example">
    <p>Schedule a local review reminder, or cancel it before it arrives.</p>
    <output aria-live="polite">{{ message }} Delivered: {{ reminders }}</output>
    <div class="example-actions">
      <button type="button" @click="scheduleReminder">Schedule reminder</button>
      <button type="button" :disabled="!isPending" @click="cancelReminder">Cancel reminder</button>
    </div>
    <p>{{ isPending ? "The reminder is pending." : "There is no pending reminder." }}</p>
  </div>
</template>

Runtime contract

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.

TimeoutFnControls

Controls returned by useTimeoutFn.

UseTimeoutOptions

Options for useTimeout.

TimeoutControls

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