From b0c9f097d2ce5965a72a1e445c33196ab1f64186 Mon Sep 17 00:00:00 2001 From: Sean Perkins Date: Wed, 2 Feb 2022 15:12:51 -0500 Subject: [PATCH] docs(datetime): example formatting date values in ISO-8601 (#24686) --- core/src/components/datetime/readme.md | 24 +++++++++++++++++++++--- 1 file changed, 21 insertions(+), 3 deletions(-) diff --git a/core/src/components/datetime/readme.md b/core/src/components/datetime/readme.md index 43c2fb76fd..f37bd5703f 100644 --- a/core/src/components/datetime/readme.md +++ b/core/src/components/datetime/readme.md @@ -147,11 +147,27 @@ const zonedTime = dateFnsTz.utcToZonedTime(date, userTimeZone); format(zonedTime, 'yyyy-MM-dd HH:mm:ssXXX', { timeZone: userTimeZone }); ``` -## Parsing Dates +## Timezones -When `ionChange` is emitted, we provide an ISO-8601 string in the event payload. From there, it is the developer's responsibility to format it as they see fit. We recommend using a library like [date-fns](https://date-fns.org) to format their dates properly. +### Assigning Date Values -Below is an example of formatting an ISO-8601 string to display the month, date, and year: +`ion-datetime` does not manipulate or read timezones. Developers will need to pass in a valid ISO-8601 string that is already configured for the user's timezone when assigning a value. If no value is provided, `ion-datetime` will default to the time specified on the user's machine (which will already be in the user's timezone). We recommend using [date-fns](https://date-fns.org) to format the date to ISO-8601. + +```typescript +import { formatISO } from 'date-fns'; + +const dateString = '2021-01-14T15:00:00.000Z'; +const formattedDateValue = formatISO(new Date(dateString)); + +// Assign `formattedDateValue` to your `ion-datetime` value. + +``` + +### Parsing Date Values + +The `ionChange` event will emit the date value as an ISO-8601 string in the event payload. It is the developer's responsibility to format it based on their application needs. We recommend using [date-fns](https://date-fns.org) to format the date value. + +Below is an example of formatting an ISO-8601 string to display the month, date and year: ```typescript import { format, parseISO } from 'date-fns'; @@ -159,6 +175,8 @@ import { format, parseISO } from 'date-fns'; /** * This is provided in the event * payload from the `ionChange` event. + * + * The value is an ISO-8601 date string. */ const dateFromIonDatetime = '2021-06-04T14:23:00-04:00'; const formattedString = format(parseISO(dateFromIonDatetime), 'MMM d, yyyy');