| -api-id | -api-type |
|---|---|
T:Windows.UI.Xaml.Controls.DatePicker |
winrt class |
Represents a control that allows a user to pick a date value.
<DatePicker .../>
Use a DatePicker to let a user enter a date value. The user picks the date using ComboBox selection for month, day, and year values. You can customize the DatePicker in various ways to suit your app.
For more info, design guidance, and code examples, see Date picker.
The DatePicker supports each of the calendar systems supported by Windows. These calendars are specified in the Windows.Globalization.CalendarIdentifiers class. The DatePicker uses the correct calendar for your app's default language, or you can set the CalendarIdentifier property to use a specific calendar system.
By default, the date picker shows the day, month, and year. If your scenario for the date picker doesn't require all the fields, you can hide the ones you don't need. To hide a field, set its corresponding fieldVisible property to false. For more info, see the DayVisible, MonthVisible, and YearVisible properties.
The string content of each ComboBox in the DatePicker is created by a DateTimeFormatter. You can use a string that is either a format template or a format pattern to specify the format. For more info, see the DayFormat, MonthFormat, and YearFormat properties.
The date picker control has both Date / DateChanged and SelectedDate / SelectedDateChanged APIs. The difference between these is that Date is not nullable, while SelectedDate is nullable.
The value of SelectedDate is used to populate the date picker and is null by default. If SelectedDate is null, the Date property is set to 12/31/1600; otherwise, the Date value is synchronized with the SelectedDate value. When SelectedDate is null, the picker is 'unset' and shows the field names instead of a date.
To use the date value in your app, you typically use a data binding to the SelectedDate property, or handle the SelectedDateChanged event.
You can set the MinYear and MaxYear properties to restrict the date values in the picker. By default, MinYear is set to 100 years prior to the current date and MaxYear is set to 100 years past the current date.
If you set only MinYear or MaxYear, you need to ensure that a valid date range is created by the date you set and the default value of the other date; otherwise, no date will be available to select in the picker. For example, setting only yearDatePicker.MaxYear = new DateTimeOffset(new DateTime(900, 1, 1)); creates an invalid date range with the default value of MinYear.
The date properties can't be set as a XAML attribute string, because the Windows Runtime XAML parser doesn't have a conversion logic for converting strings to dates as DateTime / DateTimeOffset objects.
This example demonstrates setting the SelectedDate property in code.
<DatePicker x:Name="myDatePicker"/>public MainPage()
{
this.InitializeComponent();
myDatePicker.SelectedDate = new DateTimeOffset(new DateTime(1950, 1, 1));
}The date objects used in a DatePicker have a different representation depending on your programming language. C# and Visual Basic use the System.DateTimeOffset structure that is part of .NET. Visual C++ component extensions (C++/CX) uses the Windows::Foundation::DateTime structure. A related concept is the Calendar class, which influences how dates are interpreted in context. All Windows Runtime apps can use the Windows.Globalization.Calendar class. C# and Visual Basic apps can alternatively use the System.Globalization.Calendar class, which has very similar functionality. (Windows Runtime app can use the base .NET Calendar class but not the specific implementations for example GregorianCalendar.)
.NET also supports a type named DateTime, which is implicitly convertible to a DateTimeOffset. So you might see a "DateTime" type being used in .NET code that's used to set values that are really DateTimeOffset. For more info on the difference between DateTime and DateTimeOffset, see Remarks in DateTimeOffset.
You can modify the default Style and ControlTemplate to give the control a unique appearance. For information about modifying a control's style and template, see Styling controls. The default style, template, and resources that define the look of the control are included in the generic.xaml file. For design purposes, generic.xaml is available locally with the SDK or NuGet package installation.
- WinUI Styles (recommended): For updated styles from WinUI, see
\Users\<username>\.nuget\packages\microsoft.ui.xaml\<version>\lib\uap10.0\Microsoft.UI.Xaml\Themes\generic.xaml. - Non-WinUI styles: For built-in styles, see
%ProgramFiles(x86)%\Windows Kits\10\DesignTime\CommonConfiguration\Neutral\UAP\<SDK version>\Generic\generic.xaml.
Locations might be different if you customized the installation. Styles and resources from different versions of the SDK might have different values.
XAML also includes resources that you can use to modify the colors of a control in different visual states without modifying the control template. Modifying these resources is preferred to setting properties such as Background and Foreground. For more info, see the Light-weight styling section of the XAML styles article. Light-weight styling resources are available starting in Windows 10, version 1607 (SDK 14393).
| Windows version | SDK version | Value added |
|---|---|---|
| 1607 | 14393 | LightDismissOverlayMode |
| 1809 | 17763 | SelectedDate |
| 1809 | 17763 | SelectedDateChanged |
Tip
For more info, design guidance, and code examples, see Date picker.
[!div class="nextstepaction"] Open the WinUI 2 Gallery app and see the DatePicker in action
The WinUI 2 Gallery app includes interactive examples of most WinUI 2 controls, features, and functionality. Get the app from the Microsoft Store or get the source code on GitHub.
This example shows how to create a simple date picker with a header.
<DatePicker x:Name="birthDatePicker" Header="Date of birth"/>DatePicker birthDatePicker = new DatePicker()
{
Header = "Date of birth"
};Date picker, Windows.Globalization.CalendarIdentifiers, System.DateTimeOffset (C#/VB), Windows::Foundation::DateTime (C++), Windows.Globalization.Calendar, TimePicker, Controls list