Countdown Timer

Hooks for managing countdown timers with pause, resume, and tab-visibility support.

useCountdown

Core hook. Returns remaining time in milliseconds plus controls.

import { useCountdown } from '@traveloka/utils/countdown-timer';

const {
  remaining,
  isRunning,
  isFinished,
  start,
  pause,
  resume,
  reset,
  restart,
} = useCountdown({
  duration: 30000, // ms
  interval: 1000, // tick every 1s (default)
  autoStart: false, // start immediately (default: false)
  pauseOnHidden: true, // pause when tab hidden (default: true)
  onFinish: () => console.log('done'),
  onTick: remaining => console.log(remaining),
});

Options

Prop	Type	Default	Description
duration	number	required	Total duration in ms
interval	number	1000	Tick interval in ms
autoStart	boolean	false	Start on mount
pauseOnHidden	boolean	true	Pause when tab loses focus
onFinish	() => void	—	Called when countdown reaches 0
onTick	(remaining: number) => void	—	Called on each tick

Returns

Field	Type	Description
remaining	number	Remaining time in ms
status	CountdownStatus	'idle' | 'running' | 'paused' | 'finished'
isRunning	boolean
isFinished	boolean
isIdle	boolean
start	() => void	Reset to duration and start
pause	() => void	Pause (no-op if not running)
resume	() => void	Resume from paused (no-op otherwise)
reset	() => void	Reset to duration, status → idle
restart	() => void	Reset to duration and start immediately

useCountdownSeconds

Wraps useCountdown. Same API plus hours, minutes, seconds fields derived from remaining.

import { useCountdownSeconds } from '@traveloka/utils/countdown-timer';

const { hours, minutes, seconds, isFinished, start } = useCountdownSeconds({
  duration: 3600000, // 1 hour
  autoStart: true,
});

return (
  <span>
    {hours}:{minutes}:{seconds}
  </span>
);

Additional Returns

Field	Type	Description
hours	number	Full hours remaining
minutes	number	Remaining minutes (0–59)
seconds	number	Remaining seconds (0–59)

Status Machine

stateDiagram-v2
    [*] --> idle

    idle --> running : start()
    running --> paused : pause()
    running --> idle : reset()
    running --> finished : timer hits 0
    paused --> running : resume()
    paused --> idle : reset()
    finished --> idle : reset()

    idle --> running : restart()
    running --> running : restart()
    paused --> running : restart()
    finished --> running : restart()

Notes

• pauseOnHidden auto-pauses on visibilitychange and resumes when tab becomes visible again.
• start and reset always reset remaining to duration. Use resume to continue from where it left off.
• interval precision depends on setInterval; sub-100ms values may drift.