useInterval

Timing & async

A lightweight, type-safe React hook for declarative setInterval with automatic cleanup and start/stop controls

Install

$ npm install @usefy/use-interval

Quick start

useInterval.tsx

import { useState } from "react";
import { useInterval } from "@usefy/use-interval";

function Clock() {
  const [time, setTime] = useState(() => new Date());

  useInterval(() => {
    setTime(new Date());
  }, 1000);

  return <div>{time.toLocaleTimeString()}</div>;
}

API reference

`useInterval(callback, delay, options?)`

Runs callback every delay milliseconds until unmount or stopped.

Parameters

Parameter	Type	Description
`callback`	`() => void`	Function to run on each tick (always the latest reference)
`delay`	`number \| null \| undefined`	Interval in ms, or `null`/`undefined` to disable
`options`	`UseIntervalOptions`	`{ immediate?: boolean; autoStart?: boolean }`

Options

Option	Type	Default	Description
`immediate`	`boolean`	`false`	Run the callback immediately on (re)start, then at each interval
`autoStart`	`boolean`	`true`	Start automatically on mount; when `false`, call `start()`

Returns `UseIntervalReturn`

Property	Type	Description
`start`	`() => void`	Start the interval (idempotent while already running)
`stop`	`() => void`	Stop the interval (idempotent while already stopped)
`toggle`	`() => void`	Toggle between running and stopped
`isRunning`	`boolean`	Whether the interval is ticking (started and valid delay)

Go deeper

This page is the quick reference. For every example, prop, and edge case, read the full README — or open Storybook to change props live.

Full README →Open in Storybook →