A control used for the inputting of date and time values.
- iOS 2.0+
- Mac Catalyst 13.0+
You can use a date picker to allow a user to enter either a point in time (calendar date, time value or both) or a time interval (for example for a timer). The date picker reports interactions to its associated target object.
To add a date picker to your interface:
Set the date picker mode at creation time.
Supply additional configuration options such as minimum and maximum dates if required.
Connect an action method to the date picker.
Set up Auto Layout rules to govern the position of the date picker in your interface.
You use a date picker only for handling the selection of times and dates. If you want to handle the selection of arbitrary items from a list, use a
Configuring a Date Picker
The configuration of a date picker is determined by the
date property, whose value you can set programmatically or in Interface Builder. For modes that include date or time values, you can also configure the locale, calendar, and time zone information as appropriate. The date picker uses that information when formatting date and time values for the current user, and defaults to the device’s locale, calendar and time zone. The
date property represents the currently selected date in the form of an
NSDate object, which is calendar and time zone agnostic.
date property to
UIDate allows the user to choose a duration in hours and minutes. When in this mode, the
count property represents the displayed duration, measured in seconds as an
NSTime. Note that even though you set this property in seconds, the date picker can only show values in minutes.
Figure 2 shows a date picker configured with the
date property set to
UIDate and the
minute property set to
5. The value of
count is currently
Responding to User Interaction
Date pickers use the Target-Action design pattern to notify your app when the user changes the selected date. To be notified when the date picker’s value changes, register your action method with the
UIControl event. At runtime the date picker calls your methods in response to the user selecting a date or time.
You connect a date picker to your action method using the
add method or by creating a connection in Interface Builder. The signature of an action method takes one of three forms, which are listed in Listing 1. Choose the form that provides the information that you need to respond to the value change in the date picker.
Debugging Date Pickers
When debugging issues with date pickers, watch for these common pitfalls:
The minimum date must be earlier than the maximum date. Check the bounds of your
maximumproperties. If the maximum date is less than the minimum date, both properties are ignored, and the date picker allows the selection of any date value. The minimum and maximum dates are ignored in the countdown-timer mode (
Picker Mode Count Down Timer
The minute interval must be a divisor of 60. Check that the
minutevalue can be evenly divided into 60; otherwise, the default value is used (
Interface Builder Attributes
Table 1 lists the core attributes that you configure for date pickers in Attributes Inspector within Interface Builder.
The date picker mode. Determines whether the date picker should display a time, a date, a time and date or a countdown interval. Access this value at runtime with the
The locale associated with the date picker. This property allows you to override the system default with a specific locale. You can access this attribute programmatically with the
The granularity of the minutes spinner, if it is shown in the current mode. The default value is 1, and the maximum value is 30. The value you choose must be a divisor of 60 (1, 2, 3, 4, 5, 6, 10, 12, 15, 20, 30). Access this value at runtime with the
Table 2 lists the attributes that control the display of date and time in a date picker.
The initial date that the date picker will display. Defaults to the current date, but you can set a custom value. This attribute is equivalent to setting the
The range of selectable dates displayed by the date picker. To use a dynamic range, configure the
The initial value of the date picker when used in countdown timer mode. The value is measured in seconds, but the display is in minutes.
The appearance of
UIDate is not customizable.
You should integrate date pickers in your layout using Auto Layout. Although date pickers can be resized, they should be used at their intrinsic content size.
Date pickers handle their own internationalization; the only thing you need to do is specify the appropriate locale. You can choose a specific locale for your date picker to appear in by setting the Locale (
locale) field in Attributes Inspector. This changes the language that the date picker uses for display, but also the format of the date and time (for example, certain locales present days before month names, or prefer a 24-hour clock over a 12-hour clock). The width of the date picker automatically accommodates for the length of the localization. To use the system language, leave this property set to default.
For more information, see Internationalization and Localization Guide.
Date pickers are accessible by default. Each time component in the date picker is its own accessibility element and has the Adjustable (
The accessibility value, traits, and hint for each picker wheel are spoken back to the user when VoiceOver is enabled on a device. VoiceOver speaks this information when a user taps on a picker wheel. For example, when a user taps the hours column on the Add Alarm page (Clock > Alarm > Add), VoiceOver speaks the following:
For further information about making iOS controls accessible, see the Accessibility Programming Guide for iOS.