|
2 | 2 |
|
3 | 3 | This guide explains how react-datepicker handles timezones and provides solutions for common timezone-related scenarios. |
4 | 4 |
|
5 | | -## The "Date is One Day Off" Problem (Issue #1018) |
| 5 | +## Using the `timeZone` Prop |
| 6 | + |
| 7 | +React-datepicker now supports a `timeZone` prop that allows you to display and handle dates in a specific timezone, regardless of the user's local timezone. This feature requires the optional `date-fns-tz` peer dependency. |
| 8 | + |
| 9 | +### Installation |
| 10 | + |
| 11 | +To use the `timeZone` prop, you need to install `date-fns-tz`: |
| 12 | + |
| 13 | +```bash |
| 14 | +npm install date-fns-tz |
| 15 | +# or |
| 16 | +yarn add date-fns-tz |
| 17 | +``` |
| 18 | + |
| 19 | +### Basic Usage |
| 20 | + |
| 21 | +```jsx |
| 22 | +import DatePicker from "react-datepicker"; |
| 23 | + |
| 24 | +function MyComponent() { |
| 25 | + const [startDate, setStartDate] = useState(new Date()); |
| 26 | + |
| 27 | + return <DatePicker selected={startDate} onChange={(date) => setStartDate(date)} timeZone="America/New_York" />; |
| 28 | +} |
| 29 | +``` |
| 30 | + |
| 31 | +### How It Works |
| 32 | + |
| 33 | +When you provide a `timeZone` prop: |
| 34 | + |
| 35 | +1. **Display**: Dates are displayed in the specified timezone. For example, if you select January 15th at noon UTC and the timezone is "America/New_York", the datepicker will display the date as it appears in New York time. |
| 36 | + |
| 37 | +2. **Selection**: When a user selects a date, the `onChange` callback receives a Date object that represents the selected moment in UTC. The internal conversion ensures that the date selected visually in the specified timezone is correctly converted. |
| 38 | + |
| 39 | +3. **Current Time**: The "today" indicator and default selections use the current time in the specified timezone. |
| 40 | + |
| 41 | +### Supported Timezone Formats |
| 42 | + |
| 43 | +The `timeZone` prop accepts IANA timezone identifiers: |
| 44 | + |
| 45 | +- `"UTC"` - Coordinated Universal Time |
| 46 | +- `"America/New_York"` - Eastern Time (US) |
| 47 | +- `"America/Los_Angeles"` - Pacific Time (US) |
| 48 | +- `"Europe/London"` - British Time |
| 49 | +- `"Europe/Paris"` - Central European Time |
| 50 | +- `"Asia/Tokyo"` - Japan Standard Time |
| 51 | +- `"Australia/Sydney"` - Australian Eastern Time |
| 52 | + |
| 53 | +For a complete list, see the [IANA Time Zone Database](https://www.iana.org/time-zones). |
| 54 | + |
| 55 | +### Examples |
| 56 | + |
| 57 | +#### Date and Time Picker in a Specific Timezone |
| 58 | + |
| 59 | +```jsx |
| 60 | +import DatePicker from "react-datepicker"; |
| 61 | + |
| 62 | +function TimezoneDateTimePicker() { |
| 63 | + const [date, setDate] = useState(new Date()); |
| 64 | + |
| 65 | + return <DatePicker selected={date} onChange={setDate} showTimeSelect timeZone="Europe/London" dateFormat="MMMM d, yyyy h:mm aa" />; |
| 66 | +} |
| 67 | +``` |
| 68 | + |
| 69 | +#### Date Range in UTC |
| 70 | + |
| 71 | +```jsx |
| 72 | +import DatePicker from "react-datepicker"; |
| 73 | + |
| 74 | +function UTCDateRange() { |
| 75 | + const [startDate, setStartDate] = useState(null); |
| 76 | + const [endDate, setEndDate] = useState(null); |
| 77 | + |
| 78 | + const onChange = (dates) => { |
| 79 | + const [start, end] = dates; |
| 80 | + setStartDate(start); |
| 81 | + setEndDate(end); |
| 82 | + }; |
| 83 | + |
| 84 | + return <DatePicker selected={startDate} onChange={onChange} startDate={startDate} endDate={endDate} selectsRange timeZone="UTC" />; |
| 85 | +} |
| 86 | +``` |
| 87 | + |
| 88 | +#### Inline Calendar with Timezone |
| 89 | + |
| 90 | +```jsx |
| 91 | +import DatePicker from "react-datepicker"; |
| 92 | + |
| 93 | +function TokyoCalendar() { |
| 94 | + const [date, setDate] = useState(new Date()); |
| 95 | + |
| 96 | + return <DatePicker selected={date} onChange={setDate} inline timeZone="Asia/Tokyo" />; |
| 97 | +} |
| 98 | +``` |
| 99 | + |
| 100 | +### Important Notes |
| 101 | + |
| 102 | +- **Optional Dependency**: The `timeZone` prop requires `date-fns-tz` to be installed. If it's not installed and you use the `timeZone` prop, a warning will be logged in development mode and the datepicker will fall back to local timezone behavior. |
| 103 | + |
| 104 | +- **UTC Storage**: Even when using a timezone, the Date objects passed to `onChange` represent moments in time (internally stored as UTC). The timezone only affects how dates are displayed and interpreted during selection. |
| 105 | + |
| 106 | +- **Consistency**: When using the `timeZone` prop, ensure all date-related props (like `minDate`, `maxDate`, `excludeDates`, etc.) are provided in a consistent manner. |
| 107 | + |
| 108 | +--- |
| 109 | + |
| 110 | +## The "Date is One Day Off" Problem |
6 | 111 |
|
7 | 112 | One of the most commonly reported issues is that the selected date appears to be "one day off" when converted to a string or sent to a server. This is **not a bug** in react-datepicker—it's the expected behavior of JavaScript Date objects. |
8 | 113 |
|
|
0 commit comments