react-temporal

react-temporal is a React hooks library for date and time, built on the JavaScript Temporal API. Temporal reached Stage 4 in 2026 and ships natively in Chrome 144+, Firefox 139+, and Edge 144+. This library uses native Temporal when available and falls back to a polyfill for Node.js, Safari, and older browsers.

Replace Date, Moment.js, and most date-fns use cases with immutable, time-zone-aware Temporal types — wrapped in idiomatic React hooks.

📖 Full documentation — getting started, API reference, polyfill guide, and TypeScript types.

Why Temporal in 2026?

| | Legacy Date | Temporal | | --- | --- | --- | | Immutability | Mutable | Immutable value objects | | Time zones | Error-prone offsets | First-class ZonedDateTime | | Arithmetic | Millisecond hacks | add, subtract, until, since | | Parsing | Implementation-defined | Strict ISO 8601 | | Browser support | Everywhere | Chrome 144+, Firefox 139+, Edge 144+ | | Node.js | 22+ (dev) | Use a polyfill in production (native behind flag in v24) |

Install

npm install react-temporal

Polyfill (recommended for SSR, Node.js, and Safari)

Native Temporal is used automatically when available. For environments without it, install one polyfill:

# Smaller production polyfill (~20 KB gzip) — recommended
npm install temporal-polyfill

# Official reference implementation (~44 KB gzip)
npm install @js-temporal/polyfill

For temporal-polyfill, add this once at your app entry point:

import 'temporal-polyfill/global';

@js-temporal/polyfill is installed automatically as an optional dependency and used as the fallback when native Temporal is unavailable.

Usage

All hooks are named exports. Import Temporal from the package or from your polyfill:

import { useTemporalNow, useTemporalZonedNow, Temporal } from 'react-temporal';

function Clock() {
  const now = useTemporalNow();
  const tokyo = useTemporalZonedNow('Asia/Tokyo');

  return (
    <div>
      <p>UTC: {now.toString()}</p>
      <p>Tokyo: {tokyo.toLocaleString()}</p>
    </div>
  );
}

Configurable clock

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

// Update every 100 ms for a smooth timer UI
const now = useTemporalClock({ intervalMs: 100 });

// Or get zoned time with a custom interval
const local = useTemporalNow({ timeZone: 'Europe/Madrid', intervalMs: 5000 });

Hooks

| Hook | Description | | --- | --- | | useTemporalNow | Current Instant or ZonedDateTime (with timeZone option), auto-updating | | useTemporalClock | Current Instant with configurable tick interval | | useTemporalZonedNow | Current ZonedDateTime for an IANA time zone | | useTemporalInterval | Run a callback on a Duration interval | | useTemporalDuration | Duration between two instants (start.until(end)) | | useTemporalCalendar | Validate and return a calendar ID | | useTemporalTimeZone | Validate and return a time zone ID | | useTemporalFormat | Locale-aware formatting via toLocaleString | | useTemporalRange | Inclusive array of PlainDate between two dates | | useTemporalRelative | Relative time via Intl.RelativeTimeFormat ("in 3 hours") | | useTemporalCountdown | Seconds remaining until a target instant | | useTemporalSchedule | setTimeout aligned to a target instant | | useTemporalParse | Parse an ISO string to Instant | | useTemporalDiff | Duration difference between two instants | | useTemporalWeek | All dates in the ISO week (Mon–Sun) | | useTemporalMonth | All dates in a month | | useTemporalYear | First day of each month in a year |

See examples/ for copy-paste examples, or the docs/ folder for full documentation.

Utilities

| Export | Description | | --- | --- | | Temporal | The Temporal namespace (native or polyfill) | | getTemporal() | Explicit resolver — native first, polyfill fallback |

TypeScript

Full type exports are included. Types are sourced from @js-temporal/polyfill and work with native Temporal at runtime:

import type { TemporalInstant, TemporalPlainDate, UseTemporalNowOptions } from 'react-temporal';

Testing

npm test

All hooks have unit tests in src/__tests__/.

Development

git clone https://github.com/xarlizard/react-temporal.git
cd react-temporal
nvm use 22   # requires Node.js 22+
npm install
npm test
npm run build

Contributing

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

License

MIT © xarlizard