Skip to main content

ion-datetime

shadow

Contents

Datetimes present a calendar interface and time wheel, making it easy for users to select dates and times. Datetimes are similar to the native input elements of datetime-local, however, Ionic Framework's Datetime component makes it easy to display the date and time in the a preferred format, and manage the datetime values.

Datetime Data#

Historically, handling datetime values within JavaScript, or even within HTML inputs, has always been a challenge. Specifically, JavaScript's Date object is notoriously difficult to correctly parse apart datetime strings or to format datetime values. Even worse is how different browsers and JavaScript versions parse various datetime strings differently, especially per locale.

Fortunately, Ionic Framework's datetime input has been designed so developers can avoid the common pitfalls, allowing developers to easily manipulate datetime values and give the user a simple datetime picker for a great user experience.

ISO 8601 Datetime Format: YYYY-MM-DDTHH:mmZ#

Ionic Framework uses the ISO 8601 datetime format for its value. The value is simply a string, rather than using JavaScript's Date object. Using the ISO datetime format makes it easy to serialize and parse within JSON objects and databases.

An ISO format can be used as a simple year, or just the hour and minute, or get more detailed down to the millisecond and timezone. Any of the ISO formats below can be used, and after a user selects a new value, Ionic Framework will continue to use the same ISO format which datetime value was originally given as.

DescriptionFormatDatetime Value Example
YearYYYY1994
Year and MonthYYYY-MM1994-12
Complete DateYYYY-MM-DD1994-12-15
Date and TimeYYYY-MM-DDTHH:mm1994-12-15T13:47
UTC TimezoneYYYY-MM-DDTHH:mm:ssTZD1994-12-15T13:47:20.789Z
Timezone OffsetYYYY-MM-DDTHH:mm:ssTZD1994-12-15T13:47:20.789+05:00
Hour and MinuteHH:mm13:47
Hour, Minute, SecondHH:mm:ss13:47:20

Note that the year is always four-digits, milliseconds (if it's added) is always three-digits, and all others are always two-digits. So the number representing January always has a leading zero, such as 01. Additionally, the hour is always in the 24-hour format, so 00 is 12am on a 12-hour clock, 13 means 1pm, and 23 means 11pm.

Min and Max Datetimes#

Dates are infinite in either direction, so for a user's selection there should be at least some form of restricting the dates that can be selected. By default, the maximum date is to the end of the current year, and the minimum date is from the beginning of the year that was 100 years ago.

To customize the minimum and maximum datetime values, the min and max component properties can be provided which may make more sense for the app's use-case. Following the same IS0 8601 format listed in the table above, each component can restrict which dates can be selected by the user. By passing 2016 to the min property and 2020-10-31 to the max property, the datetime will restrict the date selection between the beginning of 2016, and October 31st of 2020.

Selecting Specific Values#

While the min and max properties allow you to restrict date selection to a certain range, the monthValues, dayValues, yearValues, hourValues, and minuteValues properties allow you choose specific days and times that you to have enabled.

For example, if we wanted users to only select minutes in increments of 15, we could pass "0,15,30,45" to the minuteValues property.

As another example, if we wanted users to only select from the month of October, we could pass "10" to the monthValues property.

Customizing Date and Time Presentation#

Some use cases may call for only date selection or only time selection. The presentation property allows you to specify which pickers to show and the order to show them in. For example, presentation="time" would only show the time picker. presentation="time-date" would show the time picker first and the date picker second, but presentation="date-time" would show the date picker first and the time picker second.

Reset and Cancel Buttons#

ion-datetime provides cancel and reset methods that you can call when clicking on custom buttons that you have provided in the buttons slot. The reset method also allows you to provide a date to reset the datetime to.

Confirming Selected Values#

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.

Localization#

Ionic Framework makes use of the Intl.DatetimeFormat Web API which allows us to automatically localize the month and day names according to the language and region set on the user's device.

For instances where you need a specific locale, you can use the locale property to set it. The following example sets the language to "French" and the region to "France":

<ion-datetime locale="fr-FR"></ion-datetime>

Controlling the Hour Cycle#

ion-datetime will use the hour cycle that is specified by the locale property by default. For example, if locale is set to en-US, then ion-datetime will use a 12 hour cycle.

There are 4 primary hour cycle types:

Hour cycle typeDescription
'h12Hour system using 1–12; corresponds to 'h' in patterns. The 12 hour clock, with midnight starting at 12:00 am.
'h23'Hour system using 0–23; corresponds to 'H' in patterns. The 24 hour clock, with midnight starting at 0:00.
'h11'Hour system using 0–11; corresponds to 'K' in patterns. The 12 hour clock, with midnight starting at 0:00 am.
'h24'Hour system using 1–24; corresponds to 'k' in pattern. The 24 hour clock, with midnight starting at 24:00.

There may be scenarios where you need to have more control over which hour cycle is used. This is where the hourCycle property can help.

In the following example, we can use the hourCycle property to force ion-datetime to use the 12 hour cycle even though the locale is en-GB, which uses a 24 hour cycle by default:

<ion-datetime hour-cycle="h12" locale="en-GB"></ion-datetime>

ion-datetime also supports locale extension tags. These tags let you encode information about the locale in the locale string itself. Developers may prefer to use the extension tag approach if they are using the Intl.Locale API in their apps.

For example, if you wanted to use a 12 hour cycle with the en-GB locale, you could alternatively do:

<ion-datetime locale="en-GB-u-hc-h12"></ion-datetime>

ion-datetime currently supports the h12 and h23 hour cycle types. Interested in seeing support for h11 and h24 added to ion-datetime? Let us know!

Setting the First Day of the Week#

For ion-datetime, the default first day of the week is Sunday. As of 2021, there is no browser API that lets Ionic automatically determine the first day of the week based on a device's locale, though there is on-going work regarding this (see: TC39 GitHub).

To customize the first day of the week, developers can use the firstDayOfWeek property. This property takes in a number between 0 and 6 where 0 represents Sunday and 6 represents Saturday.

For example, if you wanted to have the first day of the week be Monday, you could set firstDayOfWeek to 1:

<ion-datetime first-day-of-week="1"></ion-datetime>

Parsing Dates#

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 to format their dates properly.

Below is an example of formatting an ISO-8601 string to display the month, date, and year:

import { format, parseISO } from 'date-fns';
/** * This is provided in the event * payload from the `ionChange` event. */const dateFromIonDatetime = '2021-06-04T14:23:00-04:00';const formattedString = format(parseISO(dateFromIonDatetime), 'MMM d, yyyy');
console.log(formattedString); // Jun 4, 2021

See https://date-fns.org/docs/format for a list of all the valid format tokens.

Advanced Datetime Validation and Manipulation#

The datetime picker provides the simplicity of selecting an exact format, and persists the datetime values as a string using the standardized ISO 8601 datetime format. However, it's important to note that ion-datetime does not attempt to solve all situations when validating and manipulating datetime values. If datetime values need to be parsed from a certain format, or manipulated (such as adding 5 days to a date, subtracting 30 minutes, etc.), or even formatting data to a specific locale, then we highly recommend using date-fns to work with dates in JavaScript.

Accessibility#

Keyboard Navigation#

ion-datetime has full keyboard support for navigating between focusable elements inside of the component. The following table details what each key does:

KeyFunction
TabMoves focus to the next focusable element.
Shift + TabMoves focus to the previous focusable element.
Space or EnterClicks the focusable element.

Date Grid#

KeyFunction
ArrowUpMoves focus to the same day of the previous week.
ArrowDownMoves focus to the same day of the next week.
ArrowRightMoves focus to the next day.
ArrowLeftMoves focus to the previous day.
HomeMoves focus to the first day of the current week.
EndMoves focus to the last day of the current week.
PageUpChanges the grid of dates to the previous month.
PageDownChanges the grid of dates to the next month.
Shift + PageUpChanges the grid of dates to the previous year.
Shift + PageDownChanges the grid of dates to the next year.

Usage#

<!-- Initial value --><ion-datetime value="2012-12-15T13:47:20.789"></ion-datetime>
<!-- Readonly --><ion-datetime readonly></ion-datetime>
<!-- Disabled --><ion-datetime disabled></ion-datetime>
<!-- Custom locale --><ion-datetime locale="en-GB"></ion-datetime>
<!-- Max and min --><ion-datetime min="1994-03-14" max="2012-12-09" value="2008-09-02"></ion-datetime>
<!-- 15 minute increments --><ion-datetime minuteValues="0,15,30,45"></ion-datetime>
<!-- Specific days/months/years --> <ion-datetime monthValues="6,7,8" yearValues="2014,2015" dayValues="01,02,03,04,05,06,08,09,10,11,12,13,14"></ion-datetime>
<!-- Selecting time, no date --><ion-datetime presentation="time"></ion-datetime>
<!-- Selecting time first, date second --><ion-datetime presentation="time-date"></ion-datetime>
<!-- Full width size --><ion-datetime size="cover"></ion-datetime>
<!-- Custom Hour Cycle --><ion-datetime hourCycle="h23"></ion-datetime>
<!-- Custom first day of week --><ion-datetime [firstDayOfWeek]="1"></ion-datetime>
<!-- Custom title --><ion-datetime>  <div slot="title">My Custom Title</div></ion-datetime>
<!-- Clear button --><ion-datetime [showClearButton]="true"></ion-datetime>
<!-- Datetime in overlay --><ion-button id="open-modal">Open Datetime Modal</ion-button><ion-modal trigger="open-modal">  <ng-template>    <ion-content>      <ion-datetime></ion-datetime>    </ion-content>  </ng-template></ion-modal>

component.html

<!-- Custom buttons --><ion-datetime>  <ion-buttons slot="buttons">    <ion-button (click)="confirm()">Good to go!</ion-button>    <ion-button (click)="reset()">Reset</ion-button>  </ion-buttons></ion-datetime>

component.ts


import { Component, ViewChild } from '@angular/core';import { IonDatetime } from '@ionic/angular';
@Component({})export class MyComponent {  @ViewChild(IonDatetime, { static: true }) datetime: IonDatetime;  constructor() {}    confirm() {    this.datetime.nativeEl.confirm();  }    reset() {    this.datetime.nativeEl.reset();  }}

Properties#

cancelText#

DescriptionThe text to display on the picker's cancel button.
Attributecancel-text
Typestring
Default'Cancel'

clearText#

DescriptionThe text to display on the picker's "Clear" button.
Attributeclear-text
Typestring
Default'Clear'

color#

DescriptionThe color to use from your application's color palette.
Default options are: "primary", "secondary", "tertiary", "success", "warning", "danger", "light", "medium", and "dark".
For more information on colors, see theming.
Attributecolor
Typestring | undefined
Default'primary'

dayValues#

DescriptionValues used to create the list of selectable days. By default
every day is shown for the given month. However, to control exactly which days of
the month to display, the dayValues input can take a number, an array of numbers, or
a string of comma separated numbers. Note that even if the array days have an invalid
number for the selected month, like 31 in February, it will correctly not show
days which are not valid for the selected month.
Attributeday-values
Typenumber | number[] | string | undefined
Defaultundefined

disabled#

DescriptionIf true, the user cannot interact with the datetime.
Attributedisabled
Typeboolean
Defaultfalse

doneText#

DescriptionThe text to display on the picker's "Done" button.
Attributedone-text
Typestring
Default'Done'

firstDayOfWeek#

DescriptionThe first day of the week to use for ion-datetime. The
default value is 0 and represents Sunday.
Attributefirst-day-of-week
Typenumber
Default0

hourCycle#

DescriptionThe hour cycle of the ion-datetime. If no value is set, this is
specified by the current locale.
Attributehour-cycle
Type"h12" | "h23" | undefined
Defaultundefined

hourValues#

DescriptionValues used to create the list of selectable hours. By default
the hour values range from 0 to 23 for 24-hour, or 1 to 12 for 12-hour. However,
to control exactly which hours to display, the hourValues input can take a number, an
array of numbers, or a string of comma separated numbers.
Attributehour-values
Typenumber | number[] | string | undefined
Defaultundefined

locale#

DescriptionThe locale to use for ion-datetime. This
impacts month and day name formatting.
The 'default' value refers to the default
locale set by your device.
Attributelocale
Typestring
Default'default'

max#

DescriptionThe maximum datetime allowed. Value must be a date string
following the
ISO 8601 datetime format standard,
1996-12-19. The format does not have to be specific to an exact
datetime. For example, the maximum could just be the year, such as 1994.
Defaults to the end of this year.
Attributemax
Typestring | undefined
Defaultundefined

min#

DescriptionThe minimum datetime allowed. Value must be a date string
following the
ISO 8601 datetime format standard,
such as 1996-12-19. The format does not have to be specific to an exact
datetime. For example, the minimum could just be the year, such as 1994.
Defaults to the beginning of the year, 100 years ago from today.
Attributemin
Typestring | undefined
Defaultundefined

minuteValues#

DescriptionValues used to create the list of selectable minutes. By default
the minutes range from 0 to 59. However, to control exactly which minutes to display,
the minuteValues input can take a number, an array of numbers, or a string of comma
separated numbers. For example, if the minute selections should only be every 15 minutes,
then this input value would be minuteValues="0,15,30,45".
Attributeminute-values
Typenumber | number[] | string | undefined
Defaultundefined

mode#

DescriptionThe mode determines which platform styles to use.
Attributemode
Type"ios" | "md"
Defaultundefined

monthValues#

DescriptionValues used to create the list of selectable months. By default
the month values range from 1 to 12. However, to control exactly which months to
display, the monthValues input can take a number, an array of numbers, or a string of
comma separated numbers. For example, if only summer months should be shown, then this
input value would be monthValues="6,7,8". Note that month numbers do not have a
zero-based index, meaning January's value is 1, and December's is 12.
Attributemonth-values
Typenumber | number[] | string | undefined
Defaultundefined

name#

DescriptionThe name of the control, which is submitted with the form data.
Attributename
Typestring
Defaultthis.inputId

presentation#

DescriptionWhich values you want to select. 'date' will show
a calendar picker to select the month, day, and year. 'time'
will show a time picker to select the hour, minute, and (optionally)
AM/PM. 'date-time' will show the date picker first and time picker second.
'time-date' will show the time picker first and date picker second.
Attributepresentation
Type"date" | "date-time" | "month" | "month-year" | "time" | "time-date" | "year"
Default'date-time'

readonly#

DescriptionIf true, the datetime appears normal but is not interactive.
Attributereadonly
Typeboolean
Defaultfalse

showClearButton#

DescriptionIf true, a "Clear" button will be rendered alongside
the default "Cancel" and "OK" buttons at the bottom of the ion-datetime
component. Developers can also use the button slot
if they want to customize these buttons. If custom
buttons are set in the button slot then the
default buttons will not be rendered.
Attributeshow-clear-button
Typeboolean
Defaultfalse

showDefaultButtons#

DescriptionIf true, the default "Cancel" and "OK" buttons
will be rendered at the bottom of the ion-datetime
component. Developers can also use the button slot
if they want to customize these buttons. If custom
buttons are set in the button slot then the
default buttons will not be rendered.
Attributeshow-default-buttons
Typeboolean
Defaultfalse

showDefaultTimeLabel#

DescriptionIf true, the default "Time" label will be rendered
for the time selector of the ion-datetime component.
Developers can also use the time-label slot
if they want to customize this label. If a custom
label is set in the time-label slot then the
default label will not be rendered.
Attributeshow-default-time-label
Typeboolean
Defaulttrue

showDefaultTitle#

DescriptionIf true, a header will be shown above the calendar
picker. On ios mode this will include the
slotted title, and on md mode this will include
the slotted title and the selected date.
Attributeshow-default-title
Typeboolean
Defaultfalse

size#

DescriptionIf cover, the ion-datetime will expand to cover the full width of its container.
If fixed, the ion-datetime will have a fixed width.
Attributesize
Type"cover" | "fixed"
Default'fixed'

value#

DescriptionThe value of the datetime as a valid ISO 8601 datetime string.
Attributevalue
Typenull | string | undefined
Defaultundefined

yearValues#

DescriptionValues used to create the list of selectable years. By default
the year values range between the min and max datetime inputs. However, to
control exactly which years to display, the yearValues input can take a number, an array
of numbers, or string of comma separated numbers. For example, to show upcoming and
recent leap years, then this input's value would be yearValues="2024,2020,2016,2012,2008".
Attributeyear-values
Typenumber | number[] | string | undefined
Defaultundefined

Events#

NameDescription
ionBlurEmitted when the datetime loses focus.
ionCancelEmitted when the datetime selection was cancelled.
ionChangeEmitted when the value (selected date) has changed.
ionFocusEmitted when the datetime has focus.

Methods#

cancel#

DescriptionEmits the ionCancel event and
optionally closes the popover
or modal that the datetime was
presented in.
Signaturecancel(closeOverlay?: boolean) => Promise<void>

confirm#

DescriptionConfirms the selected datetime value, updates the
value property, and optionally closes the popover
or modal that the datetime was presented in.
Signatureconfirm(closeOverlay?: boolean) => Promise<void>

reset#

DescriptionResets the internal state of the datetime but does not update the value.
Passing a valid ISO-8601 string will reset the state of the component to the provided date.
If no value is provided, the internal state will be reset to today.
Signaturereset(startDate?: string | undefined) => Promise<void>

CSS Custom Properties#

NameDescription
--backgroundThe primary background of the datetime component.
--background-rgbThe primary background of the datetime component in RGB format.
--title-colorThe text color of the title.

Slots#

NameDescription
buttonsThe buttons in the datetime.
time-labelThe label for the time selector in the datetime.
titleThe title of the datetime.
View Source