1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128---
productId: x-scheduler
title: React Scheduler component
packageName: '@mui/x-scheduler'
githubLabel: 'scope: scheduler'
---
# Scheduler - Timezone Support
<p class="description">Display events correctly across different timezones.</p>
{{"component": "@mui/docs/ComponentLinkHeader", "design": false}}
:::warning
This package is not published yet.
:::
TODO: Issue #20394 - Create documentation and demos
{{"demo": "TimezoneDatasetInstantBased.js", "bg": "inline", "defaultCodeOpen": false}}
## Overview
Scheduler always renders dates in the timezone defined by the `displayTimezone` prop.
Event dates (`start`, `end`, etc.) represent fixed moments in time. This means an event
always represents the same moment, regardless of the timezone in which it is displayed.
Changing `displayTimezone` only affects how the date is shown to the user, not when the
event actually happens.
For example, an event with `start: 2024-01-10T13:00:00Z`:
- is displayed as `14:00` in `Europe/Paris` (UTC+1)
- is displayed as `08:00` in `America/New_York` (UTC-5)
In all cases, it is still the same event happening at the same instant in time.
Events can optionally define a `timezone` field. This field is metadata and does not
reinterpret or shift the event start or end dates.
The `timezone` field is only used internally in situations where wall-time matters, such as:
- Recurring event rules (RRULE)
- Daylight Saving Time calculations
For example:
```ts
const event = {
start: new Date('2024-01-10T13:00:00Z'),
end: new Date('2024-01-10T14:00:00Z'),
timezone: 'Europe/Paris',
};
```
The `timezone` field does not affect the event dates. It is only used internally for recurrence and daylight saving time handling.
## Event date values
The `start` and `end` fields of an event must represent a fixed moment in time.
They are expected to be provided as JavaScript `Date` objects or timezone-aware
date objects (such as `TZDate`).
:::info
The timezone of the date object itself is not used to define event semantics.
Only the instant it represents is taken into account.
:::
## Rendering behavior
Scheduler renders all events in the timezone defined by the `displayTimezone` prop.
Changing `displayTimezone` only affects how event dates are displayed in the UI.
It does not modify the event data or change when an event occurs.
## Creating an event
When creating events from the UI, the entered date/time is interpreted in the current `displayTimezone`.
The created event does not include an explicit `timezone` field.
As a result, when the event is processed, its original timezone is treated as `"default"`.
This may evolve in future releases to allow setting the event's original timezone explicitly (for example through the UI), while still rendering all events in the selected `displayTimezone`.
## Recurring events and timezones
While single events are updated using pure instants, recurring events define
a pattern that is evaluated in a specific timezone.
For example, consider a daily recurring event that happens every day at 09:00
in the `Europe/Paris` timezone:
```ts
const event = {
start: new Date('2024-03-01T08:00:00Z'),
end: new Date('2024-03-01T09:00:00Z'),
timezone: 'Europe/Paris',
rrule: { freq: 'DAILY' },
};
```
Even when daylight saving time starts, the event continues to happen at 09:00
local time in Europe/Paris.
To achieve this, Scheduler uses the event's timezone to interpret and update
the recurrence pattern correctly.
This is the only case where Scheduler intentionally operates on day/hour semantics
instead of pure instants.
:::info
Recurring event updates are pattern-based.
This is the only case where Scheduler intentionally operates on wall-time semantics
instead of pure instants.
:::
## What Scheduler does not support yet
Scheduler currently does not support wall-time event definitions based on string dates.
This means:
- Dates without an explicit instant (for example `"2024-03-10 09:00"`) are not supported
- Event dates are not reinterpreted based on `event.timezone`
Support for string-based, wall-time event definitions is planned for a future release.