UIDatePicker: date property
The date property is the moment selected in the picker.
Value
A Date.
- Readable and writable.
- The default is the moment the picker was created.
- Precise to the millisecond: milliseconds written are preserved on read. When
minuteIntervalisn't 1, it is rounded; seeroundsToMinuteInterval. - Every read returns a new
Dateobject:picker.date !== picker.date. Changing that object doesn't affect the picker; to change the selected moment, writedate. - Writes accept only a
Date; strings and timestamps aren't converted. - A value earlier than
minimumDateor later thanmaximumDatedoesn't throw; it is changed to the nearest limit. dateis a moment in time with no time zone. The picker displays it in the device's time zone. In the date-only mode, get the year, month, and day withgetFullYear(),getMonth(), andgetDate(); don't compare the milliseconds of twodatevalues directly to decide whether they are the same day.- In
'countDownTimer'mode, the selected duration isn't indate; it is incountDownDuration.
Observing changes
When the user changes the selection, the control fires change. Writes from code don't fire it: in the acceptance tests, no change arrived within 300 milliseconds after a write.
Invalid values
Throws TypeError, and the property keeps its old value.
- Not a
Date(a string, a number):date must be a Date, got "2026-01-01". - Writing
null:date must be a Date, got null. - An invalid
Date(such asnew Date('abc')):date must be a valid Date, got an invalid one.
Examples
js
const picker = new UIDatePicker();
picker.date = new Date(2027, 0, 1);
console.log(picker.date.getFullYear(), picker.date.getMonth() + 1, picker.date.getDate());
picker.addEventListener('change', () => {
console.log('chose', picker.date.toLocaleString());
});Effect: First prints 2027 1 1. Months in new Date(2027, 0, 1) count from 0, so 0 is January. After the user changes the selection, the console prints the selected moment. The effect of user interaction is not verified in the simulator.
Corresponding iOS API
UIDatePicker.date; the native type is NSDate, here it is Date.
See also
setDate(): change it with an animationchangeeventIntl.DateTimeFormat: format a date as text for a region