diff --git a/docs/api/datetime-button.md b/docs/api/datetime-button.md index 62d4a91c7e0..c26d2ca5055 100644 --- a/docs/api/datetime-button.md +++ b/docs/api/datetime-button.md @@ -35,6 +35,14 @@ import Basic from '@site/static/usage/v7/datetime-button/basic/index.md'; The localized text on `ion-datetime-button` is determined by the `locale` property on the associated `ion-datetime` instance. See [Datetime Localization](./datetime#localization) for more details. +## Format Options + +You can customize the format of the date and time in a Datetime Button by providing `formatOptions` on the associated Datetime instance. See [Datetime Format Options](./datetime#format-options) for more details. + +import FormatOptions from '@site/static/usage/v7/datetime-button/format-options/index.md'; + + + ## Usage with Modals and Popovers `ion-datetime-button` must be associated with a mounted `ion-datetime` instance. As a result, [Inline Modals](./modal#inline-modals-recommended) and [Inline Popovers](./popover#inline-popovers) with the `keepContentsMounted` property set to `true` must be used. diff --git a/docs/api/datetime.md b/docs/api/datetime.md index cf9ed3071f7..66c0c3fa724 100644 --- a/docs/api/datetime.md +++ b/docs/api/datetime.md @@ -14,6 +14,8 @@ import MaxMin from '@site/static/usage/v7/datetime/date-constraints/max-min/inde import Values from '@site/static/usage/v7/datetime/date-constraints/values/index.md'; import Advanced from '@site/static/usage/v7/datetime/date-constraints/advanced/index.md'; +import FormatOptions from '@site/static/usage/v7/datetime/format-options/index.md'; + import CustomLocale from '@site/static/usage/v7/datetime/localization/custom-locale/index.md'; import HourCycle from '@site/static/usage/v7/datetime/localization/hour-cycle/index.md'; import FirstDayOfWeek from '@site/static/usage/v7/datetime/localization/first-day-of-week/index.md'; @@ -268,6 +270,16 @@ By default, `ion-datetime` does not show any header or title associated with the +## Format Options + +You can customize the format of the date in the header text and the time in the time button of a Datetime component by providing `formatOptions`. The `date` and `time` in the `formatOptions` property should each be an [`Intl.DateTimeFormatOptions`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat#options) object. If `formatOptions` is not provided, default formats will be used for dates and times. + +Datetime [does not manipulate or set](#time-zones) the time zone. If `timeZone` or `timeZoneName` are provided, they will be ignored, and the time zone will be set to UTC. This ensures that the displayed value matches the selected value, rather than being converted to the user's current time zone. + +Be careful with the options you provide, as they may not match the selected presentation. For example, providing `minute: 'numeric'` for a presentation of `month` may lead to unexpected behavior, displaying a month where only a time might be expected. + + + ## Buttons By default, `ionChange` is emitted with the new datetime value whenever a new date is selected. To require user confirmation before emitting `ionChange`, you can either set the `showDefaultButtons` property to `true` or use the `buttons` slot to pass in a custom confirmation button. When passing in custom buttons, the confirm button must call the `confirm` method on `ion-datetime` for `ionChange` to be emitted. diff --git a/static/usage/v7/datetime-button/format-options/angular.md b/static/usage/v7/datetime-button/format-options/angular.md new file mode 100644 index 00000000000..72570e5242b --- /dev/null +++ b/static/usage/v7/datetime-button/format-options/angular.md @@ -0,0 +1,24 @@ +```html + + + + + + + +``` diff --git a/static/usage/v7/datetime-button/format-options/demo.html b/static/usage/v7/datetime-button/format-options/demo.html new file mode 100644 index 00000000000..e768b7cbf78 --- /dev/null +++ b/static/usage/v7/datetime-button/format-options/demo.html @@ -0,0 +1,41 @@ + + + + + + Datetime Button + + + + + + + + + +
+ + + + + +
+ + + + + + diff --git a/static/usage/v7/datetime-button/format-options/index.md b/static/usage/v7/datetime-button/format-options/index.md new file mode 100644 index 00000000000..482629caa38 --- /dev/null +++ b/static/usage/v7/datetime-button/format-options/index.md @@ -0,0 +1,18 @@ +import Playground from '@site/src/components/global/Playground'; + +import javascript from './javascript.md'; +import react from './react.md'; +import vue from './vue.md'; +import angular from './angular.md'; + + diff --git a/static/usage/v7/datetime-button/format-options/javascript.md b/static/usage/v7/datetime-button/format-options/javascript.md new file mode 100644 index 00000000000..a71c653a98b --- /dev/null +++ b/static/usage/v7/datetime-button/format-options/javascript.md @@ -0,0 +1,22 @@ +```html + + + + + + + +``` diff --git a/static/usage/v7/datetime-button/format-options/react.md b/static/usage/v7/datetime-button/format-options/react.md new file mode 100644 index 00000000000..cf774d2cc98 --- /dev/null +++ b/static/usage/v7/datetime-button/format-options/react.md @@ -0,0 +1,32 @@ +```tsx +import React from 'react'; +import { IonDatetime, IonDatetimeButton, IonModal } from '@ionic/react'; + +function Example() { + return ( + <> + + + + + + + ); +} +export default Example; +``` diff --git a/static/usage/v7/datetime-button/format-options/vue.md b/static/usage/v7/datetime-button/format-options/vue.md new file mode 100644 index 00000000000..5bb7f801d98 --- /dev/null +++ b/static/usage/v7/datetime-button/format-options/vue.md @@ -0,0 +1,31 @@ +```html + + + +``` diff --git a/static/usage/v7/datetime/format-options/angular.md b/static/usage/v7/datetime/format-options/angular.md new file mode 100644 index 00000000000..8453ac416e8 --- /dev/null +++ b/static/usage/v7/datetime/format-options/angular.md @@ -0,0 +1,11 @@ +```html + + Select Date + +``` diff --git a/static/usage/v7/datetime/format-options/demo.html b/static/usage/v7/datetime/format-options/demo.html new file mode 100644 index 00000000000..0bd6dd7f8ba --- /dev/null +++ b/static/usage/v7/datetime/format-options/demo.html @@ -0,0 +1,37 @@ + + + + + + Datetime + + + + + + + + + + +
+ + Select Date + +
+ + + + + + diff --git a/static/usage/v7/datetime/format-options/index.md b/static/usage/v7/datetime/format-options/index.md new file mode 100644 index 00000000000..f12a9dc3bd2 --- /dev/null +++ b/static/usage/v7/datetime/format-options/index.md @@ -0,0 +1,18 @@ +import Playground from '@site/src/components/global/Playground'; + +import javascript from './javascript.md'; +import react from './react.md'; +import vue from './vue.md'; +import angular from './angular.md'; + + diff --git a/static/usage/v7/datetime/format-options/javascript.md b/static/usage/v7/datetime/format-options/javascript.md new file mode 100644 index 00000000000..8476e5fe8a8 --- /dev/null +++ b/static/usage/v7/datetime/format-options/javascript.md @@ -0,0 +1,13 @@ +```html + + Select Date + + + +``` diff --git a/static/usage/v7/datetime/format-options/react.md b/static/usage/v7/datetime/format-options/react.md new file mode 100644 index 00000000000..5c5bcfb2882 --- /dev/null +++ b/static/usage/v7/datetime/format-options/react.md @@ -0,0 +1,19 @@ +```tsx +import React from 'react'; +import { IonDatetime } from '@ionic/react'; + +function Example() { + return ( + + Select Date + + ); +} +export default Example; +``` diff --git a/static/usage/v7/datetime/format-options/vue.md b/static/usage/v7/datetime/format-options/vue.md new file mode 100644 index 00000000000..e24444436fc --- /dev/null +++ b/static/usage/v7/datetime/format-options/vue.md @@ -0,0 +1,17 @@ +```html + + + +```