docs: update docs for time zone

gpbl · Sep 19, 2024 · bd7e688 · bd7e688
1 parent b5e554a
commit bd7e688
Show file tree

Hide file tree

Showing 2 changed files with 49 additions and 15 deletions.
diff --git a/examples/TimeZone.tsx b/examples/TimeZone.tsx
@@ -3,17 +3,21 @@ import React, { useState } from "react";
 import { DayPicker, TZDate } from "react-day-picker";
 
 export function TimeZone() {
-  const timezone = "Pacific/Kiritimati";
+  const timeZone = "Pacific/Kiritimati";
   const [selected, setSelected] = useState<Date | undefined>(
-    TZDate.tz(timezone)
+    TZDate.tz(timeZone)
   );
   return (
     <DayPicker
       mode="single"
-      timeZone={timezone}
+      timeZone={timeZone}
       selected={selected}
       onSelect={setSelected}
-      footer={selected ? `Selected: ${selected}` : "Pick a day."}
+      footer={
+        selected
+          ? selected.toString()
+          : `Pick a day to see it is in ${timeZone} time zone.`
+      }
     />
   );
 }
diff --git a/website/docs/docs/localization.mdx b/website/docs/docs/localization.mdx
@@ -4,19 +4,14 @@ sidebar_position: 5
 
 # Localization
 
-Learn how to set the locale, adjust the starting day of the week, and apply ISO Week Dates to enhance the user experience across different regions and languages.
-
-## Locale props
-
-| Prop Name               | Type                                          | Description                                                        |
-| ----------------------- | --------------------------------------------- | ------------------------------------------------------------------ |
-| `locale`                | [`Locale`](https://date-fns.org/docs/I18n)    | Set the locale. Default is `en-US`.                                |
-| `weekStartsOn`          | `1` \| `2` \| `3` \| `4` \| `5` \| `6` \| `7` | Display the days falling into the other months.                    |
-| `firstWeekContainsDate` | `1` \| `4`                                    | Configure the first date in the first week of the year.            |
-| `ISOWeek`               | `boolean`                                     | Use [ISO Week Dates](https://en.wikipedia.org/wiki/ISO_week_date). |
+Learn how to set the locale, changing the time zone, and adjust other calendar options.
 
 ## Setting the Locale
 
+| Prop Name | Type                                       | Description                         |
+| --------- | ------------------------------------------ | ----------------------------------- |
+| `locale`  | [`Locale`](https://date-fns.org/docs/I18n) | Set the locale. Default is `en-US`. |
+
 ### 1. Install date-fns
 
 DayPicker uses the [date-fns](https://date-fns.org) library for calendar localization. To set a different locale, install `date-fns`:
@@ -64,6 +59,10 @@ import { DayPicker, defaultLocale } from "react-day-picker";
 
 ## Changing the Time Zone {#time-zone}
 
+| Prop Name  | Type     | Description                                    |
+| ---------- | -------- | ---------------------------------------------- |
+| `timeZone` | `string` | Set a time zone for the dates in the calendar. |
+
 :::warning Experimental Feature
 
 Time zones are supported by the `TZDate` object by the [@date-fns/tz](https://github.com/date-fns/tz) package. If you encounter any issues, please [report them](https://github.com/gpbl/react-day-picker/issues). Thank you!
@@ -82,8 +81,39 @@ for a list of the possible values.
   <Examples.TimeZone />
 </BrowserWindow>
 
+### Working with Time-Zoned Dates
+
+When working with time zones, make sure to use the `TZDate` object instead of the native `Date` object. The `TZDate` object is exported from [@date-fns/tz](https://github.com/date-fns/date-fns-tz). Refer to their documentation for more information.
+
+To initialize a date in a specific time zone, use the `tz` method:
+
+```tsx
+export function TimeZone() {
+  const timeZone = "America/New_York";
+  const [selected, setSelected] = useState<Date | undefined>(
+    TZDate.tz(timeZone) // Make sure you use `TZDate` instead of `Date`
+  );
+  return (
+    <DayPicker
+      mode="single"
+      timeZone={timeZone}
+      selected={selected}
+      onSelect={setSelected}
+    />
+  );
+}
+```
+
 ## Calendar Options
 
+## Locale props
+
+| Prop Name               | Type                                          | Description                                                        |
+| ----------------------- | --------------------------------------------- | ------------------------------------------------------------------ |
+| `weekStartsOn`          | `1` \| `2` \| `3` \| `4` \| `5` \| `6` \| `7` | Display the days falling into the other months.                    |
+| `firstWeekContainsDate` | `1` \| `4`                                    | Configure the first date in the first week of the year.            |
+| `ISOWeek`               | `boolean`                                     | Use [ISO Week Dates](https://en.wikipedia.org/wiki/ISO_week_date). |
+
 ### First Date of the Week
 
 Use the `weekStartsOn` prop to set the first day of the week.
@@ -126,7 +156,7 @@ Use the `ISOWeek` prop to switch to [ISO Week Dates](https://en.wikipedia.org/wi
 
 DayPicker supports the Jalali calendar through the [date-fns-jalali](https://www.npmjs.com/package/date-fns-jalali) package. To switch to the Jalali calendar, add `date-fns-jalali` to your dependencies and import `DayPicker` from `react-day-picker/jalali`.
 
-:::note Experimental feature
+:::warning Experimental Feature
 
 Support for the Jalali calendar is an experimental feature. [Please report](https://github.com/gpbl/react-day-picker/issues) any issues you encounter. Thank you!