useCountdown

Installation

npm install @1hook/use-countdown

Usage

import { useCountdown } from '@1hook/use-countdown'

Get the remaining milliseconds:

const milliseconds = useCountdown({
  to: '2026-01-01',
})

Transform the remaining time in seconds:

const seconds = useCountdown({
  to: '2026-01-01',
  transform: (ms) => Math.ceil(ms / 1000),
})

Use a custom interval between each tick:

const seconds = useCountdown({
  to: '2026-01-01',
  interval: 100,
})

Prevent rerendering the component on every tick:

useCountdown({
  to: '2026-01-01',
  trackState: false,
  onTick: (ms) => console.log(ms),
})

Synchronize all countdowns using the same interval:

const milliseconds = useCountdown({
  to: '2026-01-01',
  sync: true,
})

Add more details on the current countdown state:

const { seconds, state } = useCountdown({
  to: '2026-01-01',
  transform(ms, to) {
    const seconds = Math.ceil(ms / 1000)
    return {
      state: to ? (seconds <= 0 ? 'expired' : 'ticking') : 'idle',
      seconds,
    }
  },
})

Background Tabs

Browsers throttle intervals in background tabs, which can leave the countdown stale. When the tab becomes visible again, the countdown immediately resamples the remaining time and triggers onTick.

API Reference

UseCountdownOptions

The options of the `useCountdown` hook.

Prop	Type	Default
`sync?`	`boolean`	`false`
`trackState?`	`boolean`	`true`
`onExpire?`	`(() => void)`	-
`onTick?`	`((value: T) => void)`	-
`transform?`	`((ms: number, to: To) => T)`	-
`interval?`	`number \| ((remainingMs: number) => number)`	`1000`
`to`	`Date \| string \| null \| undefined \| false`	-