This is documentation for Ionic Documentation v5, which is no longer actively maintained.
For up-to-date documentation, see the latest version (v7).
Version: v5
ion-datetime
Datetimes present a picker interface from the bottom of a page, making it easy for
users to select dates and times. The picker displays scrollable columns that can be
used to individually select years, months, days, hours and minute values. Datetimes
are similar to the native input elements of type datetime-local, however, Ionic's
Datetime component makes it easy to display the date and time in a preferred format,
and manage the datetime values.
The datetime component displays the values in two places: in the <ion-datetime> component,
and in the picker interface that is presented from the bottom of the screen. The following
chart lists all of the formats that can be used.
The displayFormat property specifies how a datetime's value should be
printed, as formatted text, within the datetime component.
A few examples are provided in the chart below. The formats mentioned
above can be passed in to the display format in any combination.
Display Format
Example
M-YYYY
6-2005
MM/YY
06/05
MMM YYYY
Jun 2005
YYYY, MMMM
2005, June
MMM DD, YYYY HH:mm
Jun 17, 2005 11:06
Important: ion-datetime will by default display values relative to the user's timezone.
Given a value of 09:00:00+01:00, the datetime component will
display it as 04:00:00-04:00 for users in a -04:00 timezone offset.
To change the display to use a different timezone, use the displayTimezone property described below.
The displayTimezone property allows you to change the default behavior
of displaying values relative to the user's local timezone. In addition to "UTC" valid
time zone values are determined by the browser, and in most cases follow the time zone names
of the IANA time zone database, such as "Asia/Shanghai",
"Asia/Kolkata", "America/New_York". In the following example:
The pickerFormat property determines which columns should be shown in the picker
interface, the order of the columns, and which format to use within each
column. If pickerFormat is not provided then it will use the value of
displayFormat. Refer to the chart in the Display Format section
for some formatting examples.
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's datetime input has been designed so developers can avoid
the common pitfalls, allowing developers to easily format datetime values within
the input, and give the user a simple datetime picker for a great user
experience.
Ionic 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 will continue to use
the same ISO format which datetime value was originally given as.
Description
Format
Datetime Value Example
Year
YYYY
1994
Year and Month
YYYY-MM
1994-12
Complete Date
YYYY-MM-DD
1994-12-15
Date and Time
YYYY-MM-DDTHH:mm
1994-12-15T13:47
UTC Timezone
YYYY-MM-DDTHH:mm:ssTZD
1994-12-15T13:47:20.789Z
Timezone Offset
YYYY-MM-DDTHH:mm:ssTZD
1994-12-15T13:47:20.789+05:00
Hour and Minute
HH:mm
13:47
Hour, Minute, Second
HH:mm:ss
13: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.
Also note that neither the displayFormat nor the pickerFormat
can set the datetime value's output, which is the value that is set by the
component's ngModel. The formats are merely for displaying the value as text
and the picker's interface, but the datetime's value is always persisted as a
valid ISO 8601 datetime string.
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, rather than the default of the last 100 years. 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.
At this time, there is no one-size-fits-all standard to automatically choose the
correct language/spelling for a month name, or day of the week name, depending
on the language or locale.
However, at this time the standard has not been fully implemented by all popular browsers
so Ionic is unavailable to take advantage of it yet.
Additionally, Angular also provides an internationalization service, but it is still
under heavy development so Ionic does not depend on it at this time.
The current best practice is to provide an array of names if the app needs to use names other
than the default English version of month and day names. The month names and day names can be
either configured at the app level, or individual ion-datetime level.
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.
Short abbreviated day of the week names. This can be used to provide locale names for each day in the week. Defaults to English. Defaults to: ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat']
Values 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.
The display format of the date and time as text that shows within the item. When the pickerFormat input is not used, then the displayFormat is used for both display the formatted text, and determining the datetime picker's columns. See the pickerFormat input description for more info. Defaults to MMM D, YYYY.
The timezone to use for display purposes only. See Date.prototype.toLocaleString() for a list of supported timezones. If no value is provided, the component will default to displaying times in the user's local timezone.
Values 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.
The 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.
The 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.
Values 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".
Values 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.
The format of the date and time picker columns the user selects. A datetime input can have one or many datetime parts, each getting their own column which allow individual selection of that particular datetime part. For example, year and month columns are two individually selectable columns which help choose an exact date from the datetime picker. Each column follows the string parse format. Defaults to use displayFormat.
Values 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".