usehmtimer

Of course! 🚀
Let’s make you a professional and clean README.md for your package usehmtimer.

Here’s a full version you can directly use:

usehmtimer

⏳ A lightweight React hook for handling timers, countdowns, and time-ago formatting easily!

✨ Features

• 🕐 Timer — Start, stop, reset a simple timer.
• 📅 Countdown — Calculate remaining time to a future target date.
• 🌎 Localized "Time Ago" — Format time ago in English or Arabic.
• ⚡ Built with TypeScript — Full types support.
• 📦 Small and tree-shakable.

📦 Installation

npm install usehmtimer

or with yarn:

yarn add usehmtimer

🚀 Usage

import useMyTimer from "usehmtimer";

function MyComponent() {
  const { timeAgo, seconds, remaining, StartTimer, StopTimer, ResetTimer } =
    useMyTimer({ targetDate: "2025-12-31T23:59:59" });

  return (
    <div>
      <p>Timer seconds: {seconds}</p>
      <p>Remaining Days: {remaining.days}</p>
      <button onClick={StartTimer}>Start</button>
      <button onClick={StopTimer}>Stop</button>
      <button onClick={ResetTimer}>Reset</button>
    </div>
  );
}

🛠️ API

useMyTimer(props?: UseMyTimerProps)

Prop	Type	Description
targetDate	string	(Optional) ISO string of the future target date, e.g., "2025-12-31T23:59:59".

Returned Values:

Name	Type	Description
timeAgo(date1, date2, lang?)	(string, string, "ar" | "en") => string	Calculate time difference human-readable (e.g., "2 hours ago").
seconds	number	Timer seconds since started.
remaining	DateSections	Object containing { years, months, days, hours, minutes, seconds } till targetDate.
StartTimer	() => void	Start the seconds timer.
StopTimer	() => void	Stop the timer.
ResetTimer	() => void	Reset seconds to 0.

📚 Types

type DateSections = {
  years: number;
  months: number;
  days: number;
  hours: number;
  minutes: number;
  seconds: number;
};

interface UseMyTimerProps {
  targetDate?: string;
}

⚖ License

MIT © Habib Mohammed

🙌 Contributing

Feel free to open issues or pull requests to improve this hook!
PRs and ideas are very welcome ✨

📢 Notes

• If you use remaining, it's better to pass a targetDate to useMyTimer.
• Fully compatible with React 18+ and React 19.

Would you like me also to make you a small badge section (like "npm version", "bundle size", etc.)? 🚀✨ It will make your README look even cooler! 🎖️
Want me to add it? 🎨👑