https://github.com/xarlizard/react-temporal
A comprehensive React hooks library for date and time management using the JavaScript Temporal API. Provides custom hooks for all common date, time, calendar, and timezone needs in React projects.
https://github.com/xarlizard/react-temporal
npm-package react temporal-polyfill
Last synced: 5 months ago
JSON representation
A comprehensive React hooks library for date and time management using the JavaScript Temporal API. Provides custom hooks for all common date, time, calendar, and timezone needs in React projects.
- Host: GitHub
- URL: https://github.com/xarlizard/react-temporal
- Owner: xarlizard
- License: mit
- Created: 2025-07-21T11:03:26.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2025-07-21T15:17:06.000Z (11 months ago)
- Last Synced: 2025-07-21T15:41:13.543Z (11 months ago)
- Topics: npm-package, react, temporal-polyfill
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/@xarlizard/react-temporal
- Size: 164 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# react-temporal
[](https://badge.fury.io/js/@xarlizard%2Freact-temporal)
[](https://opensource.org/licenses/MIT)
[](https://www.typescriptlang.org/)
[](https://github.com/xarlizard/react-temporal/actions/workflows/publish.yml)
[](https://github.com/xarlizard/react-temporal/actions/workflows/deploy.yml)
**react-temporal** is a comprehensive React hooks library for date and time management, powered by the new JavaScript
[Temporal API](https://tc39.es/proposal-temporal/). It aims to be the only required library for handling dates, times,
durations, calendars, and time zones in React projects.
---
## 🚀 Install
```bash
npm install @xarlizard/react-temporal
```
---
## 📦 Usage
All hooks are named exports:
```tsx
import { useTemporalNow, useTemporalMonth } from 'react-temporal';
function Clock() {
const now = useTemporalNow();
return
Current time: {now.toString()};
}
```
---
## 🧩 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.
```tsx
const now = useTemporalNow();
```
#### `useTemporalMonth`
Returns all dates in the month of a given `Temporal.PlainDate`.
```tsx
const dates = useTemporalMonth(Temporal.PlainDate.from('2025-07-01'));
```
#### `useTemporalCountdown`
Returns the remaining seconds until a target `Temporal.Instant`.
```tsx
const remaining = useTemporalCountdown(Temporal.Instant.from('2025-08-01T00:00:00Z'));
```
#### ...and many more!
See [`examples/`](examples/README.md) for more usage patterns.
---
## 🧪 Testing
All hooks are covered by unit tests in [`src/__tests__/`](src/__tests__). Run tests with:
```bash
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](https://github.com/xarlizard)