react-temporal

react-temporal is a comprehensive React hooks library for date and time management, powered by the new JavaScript Temporal API. It aims to be the only required library for handling dates, times, durations, calendars, and time zones in React projects.

---

🚀 Install

npm install @xarlizard/react-temporal

---

📦 Usage

All hooks are named exports:

import { useTemporalNow, useTemporalMonth } from 'react-temporal';

function Clock() {
  const now = useTemporalNow();
  return <div>Current time: {now.toString()}</div>;
}

---

🧩 Hooks Overview

Hook	Description
useTemporalNow	Returns the current Temporal.Instant, updating every second.
useTemporalInterval	Runs a callback at a given Temporal.Duration interval.
useTemporalDuration	Returns a Temporal.Duration between two instants.
useTemporalCalendar	Returns a Temporal.Calendar instance for a given calendar ID.
useTemporalTimeZone	Returns a Temporal.TimeZone instance for a given time zone ID.
useTemporalFormat	Formats a Temporal object using Intl.DateTimeFormat.
useTemporalRange	Returns an array of Temporal.PlainDate between start and end.
useTemporalRelative	Returns a human-readable relative time string between two instants.
useTemporalCountdown	Returns the remaining seconds until a target instant.
useTemporalSchedule	Schedules a callback to run at a specific instant.
useTemporalParse	Parses an ISO string to Temporal.Instant.
useTemporalDiff	Returns the difference between two instants as a Temporal.Duration.
useTemporalWeek	Returns all dates in the week of a given Temporal.PlainDate.
useTemporalMonth	Returns all dates in the month of a given Temporal.PlainDate.
useTemporalYear	Returns all months in the year of a given Temporal.PlainDate.

---

Example Hooks

useTemporalNow

Returns the current Temporal.Instant, updating every second.

const now = useTemporalNow();

useTemporalMonth

Returns all dates in the month of a given Temporal.PlainDate.

const dates = useTemporalMonth(Temporal.PlainDate.from('2025-07-01'));

useTemporalCountdown

Returns the remaining seconds until a target Temporal.Instant.

const remaining = useTemporalCountdown(Temporal.Instant.from('2025-08-01T00:00:00Z'));

...and many more!

See examples/ for more usage patterns.

---

🧪 Testing

All hooks are covered by unit tests in src/__tests__/. Run tests with:

npm test

---

🛠️ Development

• Clone the repo: git clone https://github.com/xarlizard/react-temporal.git
• Install dependencies: npm install
• Run tests: npm test
• Build: npm run build

---

🤝 Contributing

Contributions are welcome! Please open issues or submit pull requests.

---

📄 License

MIT © xarlizard