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,
    }
  },
})

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`	`1000`
`to`	`Date \| string \| null \| undefined \| false`	-

useCountdown

Installation

Usage

API Reference

UseCountdownOptions

On this page