A control used for the inputting of date and time values.


@interface UIDatePicker : UIControl


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 UIPickerView object.

Configuring a Date Picker

The configuration of a date picker is determined by the datePickerMode 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.

To limit the range of dates that the user can select, assign values to the minimumDate and maximumDate properties. You can also use the minuteInterval property to allow only specific time increments.

Setting the datePickerMode property to UIDatePickerModeCountDownTimer allows the user to choose a duration in hours and minutes. When in this mode, the countDownDuration property represents the displayed duration, measured in seconds as an NSTimeInterval. 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 datePickerMode property set to UIDatePickerModeCountDownTimer and the minuteInterval property set to 5. The value of countDownDuration is currently 4500.

Figure 2

Date picker displaying a duration.

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 UIControlEventValueChanged 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 addTarget:action:forControlEvents: 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.

Listing 1

Action methods for date pickers

- (IBAction)doSomething;
- (IBAction)doSomething:(id)sender;
- (IBAction)doSomething:(id)sender forEvent:(UIEvent*)event;

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 minimumDate and maximumDate properties. 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 (UIDatePickerModeCountDownTimer).

  • The minute interval must be a divisor of 60. Check that the minuteInterval value can be evenly divided into 60; otherwise, the default value is used (1).

Interface Builder Attributes

Table 1 lists the core attributes that you configure for date pickers in Attributes Inspector within Interface Builder.

Table 1

Core attributes




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 datePickerMode property.


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 locale property.


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 minuteInterval property.

Table 2 lists the attributes that control the display of date and time in a date picker.

Table 2

Time attributes




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 date property programmatically.


The range of selectable dates displayed by the date picker. To use a dynamic range, configure the minimumDate and maximumDate properties programmatically. The date picker ignores these options when the Mode attribute is set to Count Down Timer.


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.

For information about the date picker’s inherited Interface Builder attributes, see UIControl and UIView.


The appearance of UIDatePicker 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 (UIAccessibilityTraitAdjustable) trait.

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:

"2 o'clock. Picker item. Adjustable. Swipe up or down with one finger to adjust the value.”

For further information about making iOS controls accessible, see the Accessibility Programming Guide for iOS.


Managing the Date and Calendar


The calendar to use for the date picker.


The date displayed by the date picker.


The locale used by the date picker.

- setDate:animated:

Sets the date to display in the date picker, with an option to animate the setting.


The time zone reflected in the date displayed by the date picker.

Configuring the Date Picker Mode


The mode of the date picker.

Configuring Temporal Attributes


The maximum date that a date picker can show.


The minimum date that a date picker can show.


The interval at which the date picker should display minutes.


The value displayed by the date picker when the mode property is set to show a countdown time.



The mode displayed by the date picker.


Inherits From

Conforms To

See Also



The base class for controls, which are visual elements that convey a specific action or intention in response to user interactions.


A control that executes your custom code in response to user interactions.


A control that displays a horizontal series of dots, each of which corresponds to a page in the app’s document or other data-model entity.


A horizontal control made of multiple segments, each segment functioning as a discrete button.


A control used to select a single value from a continuous range of values.


A control used to increment or decrement a value.


A control that offers a binary choice, such as On/Off.