🕓 React Timezone Range Picker

Flexible, Mantine-powered UI components for building timezone-aware date and time range pickers.

✨ Features

• 📅 Basic picker by default with a date-only range field and scrollable day quick ranges
• 🛠️ Advanced mode with separate start/end date and time fields, relative ranges, around-time selection, and timezone changes
• 🌍 Timezone-aware display and conversion via the Temporal API with an old-browser polyfill
• 🎨 Mantine 9 components for accessibility and theming
• ⚡️ TypeScript support with generated definitions
• 🪶 Lightweight build via vite, tree-shakeable ESM + CJS outputs

Picker modes

Basic mode

The picker opens in basic mode on every mount. It provides a compact date-only range field and day-based quick options. Date and quick-option selections are applied immediately without an Apply button, and both returned times are set to 00:00:00.

Select Advanced to open the full picker. In Advanced mode, use the Basic button on the left side of the footer to return to Basic mode.

Advanced mode

Advanced mode provides the full picker with separate start/end date and time fields, relative time options, around-time selection, and timezone selection. Changes to its form-based panels are submitted with the Apply button.

Restricting past or future ranges

Set options.allowedTimeRange to "past", "future", or "all" (the default). This filters quick options, limits date pickers, and validates date/time input against the current time in the selected timezone.

<TimezoneRangePicker
  {...range}
  onApply={handleTimeRangeApply}
  options={{
    allowedTimeRange: "future",
    // Adds today as a whole calendar day to Last/Next day ranges
    includeTodayInQuickRanges: true,
  }}
/>

Today, Yesterday, and Tomorrow use complete calendar-day boundaries (for example, Today 00:00 through Tomorrow 00:00). By default, Last 2 days and Next 2 days select two complete days before or after today. Set includeTodayInQuickRanges to true to add the complete current day to those ranges.

📦 Installation

# npm
npm install react-timezone-range-picker

# yarn
yarn add react-timezone-range-picker

# pnpm
pnpm add react-timezone-range-picker

Peer dependencies:
You must install these in your project:

• react (>=19.2.0)
• react-dom (>=19.2.0)
• @mantine/core (>=9.5.2)
• @mantine/dates (>=9.5.2)
• @mantine/form (>=9.5.2)
• @mantine/hooks (>=9.5.2)

Usage

import { useState } from "react";
import {
  TimezoneRangePicker,
  type OnApplyParams,
  type TimezoneData,
} from "react-timezone-range-picker";
// Should import the css to make sure the application works
import "react-timezone-range-picker/style.css";

const DEFAULT_TIMEZONE = {
  name: "Asia/Tokyo",
  longName: "Japan Standard Time",
  utcOffset: "+09:00",
};

const DEFAULT_RANGE = {
  startDate: "2025/06/10",
  startTime: "09:00:00",
  endDate: "2025/06/11",
  endTime: "18:00:00",
  timezone: DEFAULT_TIMEZONE,
};

type TzRange = {
  startDate: string | null;
  startTime: string | null;

  endDate: string | null;
  endTime: string | null;

  timezone: TimezoneData;
};

function App() {
  const [range, setRange] = useState<TzRange>(DEFAULT_RANGE);

  const handleTimeRangeApply = ({
    startDate,
    startTime,
    endDate,
    endTime,
    timezone,
  }: OnApplyParams) => {
    setRange({ startDate, startTime, endDate, endTime, timezone });
  };

  return (
    <TimezoneRangePicker
      {...range}
      onApply={handleTimeRangeApply}
      buttonStyle={{ height: "50px", fontSize: "13px", fontWeight: 300 }}
    />
  );
}