react-time-tools

  

🧩 React Time Tools — Time Management Utilities for React

A lightweight and precise hook collection designed to simplify working with time in React apps. Whether you're building timers, scheduling tasks, showing relative time, or running time-based interactions — this library offers intuitive, production-ready solutions.

---

🔧 Feature Summary

| Hook | Description |
| ------------------------------------------ | -------------------------------------- |
| useCountdown | Countdown timer with full control |
| useCurrentTime | Real-time time tracking and formatting |
| useDebouncedTime | Debounce value updates |
| useInterval | Safe recurring logic |
| useStopwatch | Stopwatch with laps |
| useTimeAgo | Relative "X mins ago" strings |
| useTimeComparison | Check if now is between two times |
| useTimeScheduler | Repeat task every N ms |
| useTimeSpeed | Simulated fast/slow time flow |
| useTimeoutEffect | Trigger effect once after delay |

---

$3

Countdown with control over timing.

Arguments:

- initialSeconds: number
- options?: { onEnd?: () => void }

Returns:

- minutes: number, seconds: number
- start(), pause(), reset(newSeconds?)
- isRunning: boolean

``tsx
import { useCountdown } from "react-time-tools";

function CountdownTimer() {
const { minutes, seconds, start, pause, reset } = useCountdown(90);
return (



);
}
`

Use case: countdowns in forms, quizzes, games.

---

$3

Track and format the current time in real-time.

Arguments:

- format?: '12-hour' | '24-hour'
- interval?: number (default: 1000)
- withMilliseconds?: boolean

Returns:

- time: Date
- formattedTime: string

`tsx
const { time, formattedTime } = useCurrentTime({
format: "12-hour",
interval: 1000,
});
`

Use case: live clocks, time displays, dashboards.

`tsx
import { useCurrentTime } from "react-time-tools";

export function LiveClock() {
const { formattedTime } = useCurrentTime({ format: "24-hour" });
return

;
}
`

---

$3

Delay value updates until user stops interacting.

Arguments:

- value: T
- delay: number

Returns:

- T

``tsx
import { useDebouncedTime } from 'react-time-tools';
import { useState, useEffect } from 'react';

function DebouncedInput() {
const [input, setInput] = useState('');
const debounced = useDebouncedTime(input, 500);

useEffect(() => {
if (debounced) console.log('Search:', debounced);
}, [debounced]);

return setInput(e.target.value)} />;
}
`tsx
const debounced = useDebouncedTime(input, 500);
``

Use case: debounced search, user input.

---

$3

Call a function at regular intervals (safe version of setInterval).

Arguments:

- callback: () => void
- delay: number | null

``tsx
import { useInterval } from 'react-time-tools';

function TimerTick() {
const [count, setCount] = useState(0);
useInterval(() => setCount((c) => c + 1), 1000);

return

Ticks: {count}

;
}
`tsx
useInterval(() => setCount((c) => c + 1), 1000);
``

Use case: polling, timers, animations.

---

$3

Track time and record laps.

Returns:

- time: { minutes, seconds, milliseconds }
- laps: number[]
- start(), pause(), reset(), addLap()
- isRunning: boolean

`tsx
import { useStopwatch } from "react-time-tools";

function Stopwatch() {
const { time, laps, start, pause, reset, addLap } = useStopwatch();
return (



);
}
`

Use case: stopwatch apps, profiling, logging.

---

$3

Convert a Date to a human-readable relative string.

Arguments:

- date: Date

Returns:

- string

``tsx
import { useTimeAgo } from 'react-time-tools';

function MessageTime({ sentAt }: { sentAt: Date }) {
const timeAgo = useTimeAgo(sentAt);
return {timeAgo};
}
`tsx
const timeAgo = useTimeAgo(new Date('2024-01-01T10:00:00Z'));
``

Use case: messaging, logging, news feeds.

---

$3

Check if the current time is between two values.

Arguments:

- start: string | Date | number
- end: string | Date | number

Returns:

- boolean

``tsx
import { useTimeComparison } from 'react-time-tools';

function WorkingHoursNotice() {
const isWorking = useTimeComparison({ start: '09:00', end: '18:00' });
return

;
}
`tsx
const isWorking = useTimeComparison({ start: '09:00', end: '18:00' });
``

Use case: working hours logic, time-based UI.

---

$3

Run a task repeatedly at a fixed interval.

Arguments:

- intervalMs: number
- task: () => void

``tsx
import { useTimeScheduler } from 'react-time-tools';

function AutoFetcher() {
const [data, setData] = useState(null);
useTimeScheduler({ intervalMs: 60000, task: () => fetch('/api').then(r => r.json()).then(setData) });

return

{JSON.stringify(data, null, 2)}

;
}
`tsx
useTimeScheduler({ intervalMs: 1800000, task: () => refreshData() });
``

Use case: periodic fetch, cache refresh.

---

$3

Simulate accelerated or slowed-down time flow — great for games, timelines, or demo modes.

Arguments:

- initialSpeed?: number — multiplier of real time (e.g. 2 = twice as fast)

Returns:

- time: Date — simulated time
- setSpeed: (multiplier: number) => void — function to change the speed

`tsx
const { time, setSpeed } = useTimeSpeed({ initialSpeed: 2 });
`

Use case: simulations, demos, timeline scrubbing.

`tsx
import { useTimeSpeed } from "react-time-tools";

export function SimulatedClock() {
const { time, setSpeed } = useTimeSpeed({ initialSpeed: 2 });
return (



);
}
`

---

$3

Run a callback after a delay, with automatic cleanup.

Arguments:

- callback: () => void
- delay: number

``tsx
import { useTimeoutEffect } from 'react-time-tools';

function DelayedNotice() {
const [visible, setVisible] = useState(true);
useTimeoutEffect(() => setVisible(false), 5000);

return visible ?

Visible for 5 seconds

: null;
}
`tsx
useTimeoutEffect(() => doSomething(), 3000);
``

Use case: alerts, feedback banners, auto-dismiss.

---

📦 Installation

`bash
npm install react-time-tools
`

✅ Why React Time Tools?

- 🧠 Intuitive API
- 🧼 Automatic cleanup (no memory leaks)
- 🧰 Perfect for dashboards, games, productivity tools, and real-time UIs
- 💡 Works great with hooks like useEffect, useState`, and more
- 📦 Zero external runtime dependencies

---

🧪 Example Use Cases

- Live clocks, time displays
- Interactive countdowns or stopwatches
- Scheduling API calls
- Demos and simulations with time acceleration
- Time-based UI toggles

---

License

MIT

---

Made with ❤️ for React developers working with time.