Getting Started with WinUI Calendar Date Picker

22 Jul 202618 minutes to read

This section explains the steps required to add the WinUI Calendar Date Picker control and its date selection options. This section covers only basic features needed to get started with Syncfusion Calendar Date Picker control.

Structure of Calendar Date Picker control

Creating an application with WinUI Calendar Date Picker

1. Create a WinUI 3 desktop app for C# and .NET 5.
2. Add reference to the Syncfusion.Calendar.WinUI NuGet package.
3. Import the control namespace Syncfusion.UI.Xaml.Calendar in XAML or C# code.

4. Initialize the SfCalendarDatePicker control.

   MainWindow.xaml

   <Window
       x:Class="GettingStarted.MainWindow"
       xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
       xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
       xmlns:local="using:GettingStarted"
       xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
       xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
       xmlns:calendar="using:Syncfusion.UI.Xaml.Calendar"
       mc:Ignorable="d">
       <Grid Name="grid">
           <!--Adding Calendar Date Picker control -->
           <calendar:SfCalendarDatePicker Name="sfCalendarDatePicker"/>
       </Grid>
   </Window>

   MainWindow.xaml.cs

   using Syncfusion.UI.Xaml.Calendar;
   
   namespace GettingStarted
   {
       /// <summary>
       /// An empty page that can be used on its own or navigated to within a Frame.
       /// </summary>
       public sealed partial class MainWindow : Window
       {
           public MainWindow()
           {
               this.InitializeComponent();
               // Creating an instance of the Calendar control
               SfCalendarDatePicker sfCalendarDatePicker = new SfCalendarDatePicker();
               this.Content = sfCalendarDatePicker;
           }
       }
   }

NOTE

Download demo application from GitHub.

Select the date programmatically

You can set or change the selected date programmatically by using the SelectedDate property. If no value is assigned to the SelectedDate property, the Calendar Date Picker will automatically assign the current system date as the SelectedDate.

MainWindow.xaml.cs

using Syncfusion.UI.Xaml.Calendar;

SfCalendarDatePicker sfCalendarDatePicker = new SfCalendarDatePicker();
sfCalendarDatePicker.SelectedDate = new DateTimeOffset(new DateTime(2021, 01, 06));

NOTE

Download demo application from GitHub.

Select date interactively

You can change the selected date interactively by entering the date value using the keyboard or by selecting from the drop-down calendar menu. You can also get the selected date from the SelectedDate property.

MainWindow.xaml

<Window
    ...
     xmlns:calendar="using:Syncfusion.UI.Xaml.Calendar">
    <calendar:SfCalendarDatePicker Name="sfCalendarDatePicker" />
</Window>

MainWindow.xaml.cs

using Syncfusion.UI.Xaml.Calendar;

SfCalendarDatePicker sfCalendarDatePicker = new SfCalendarDatePicker();

NOTE

Download demo application from GitHub.

Setting null value

If you want to set a null value for the Calendar Date Picker, set the AllowNull property as true and set the SelectedDate property as null. If the AllowNull property is false, then the current system date is updated in the SelectedDate property and displayed instead of null.

MainWindow.xaml

<Window
    ...
     xmlns:calendar="using:Syncfusion.UI.Xaml.Calendar">
    <calendar:SfCalendarDatePicker Name="sfCalendarDatePicker"
                                   SelectedDate="{x:Null}"
                                   AllowNull="True"
                                    />
</Window>

MainWindow.xaml.cs

using Syncfusion.UI.Xaml.Calendar;

SfCalendarDatePicker sfCalendarDatePicker = new SfCalendarDatePicker();
sfCalendarDatePicker.SelectedDate = null;
sfCalendarDatePicker.AllowNull = true;

NOTE

Download demo application from GitHub.

Header and description

This section explains the Header and Description properties of the CalendarDatePicker.

Header

The Header property is used to display the title for the CalendarDatePicker control.

MainWindow.xaml

<Window
    ...
     xmlns:calendar="using:Syncfusion.UI.Xaml.Calendar">
    <calendar:SfCalendarDatePicker x:Name="CalendarDatePicker"
                                  Header="Enter your date of birth"
                                  Width="180"
                                  Height="60" />
</Window>

MainWindow.xaml.cs

using Syncfusion.UI.Xaml.Calendar;

SfCalendarDatePicker calendarDatePicker = new SfCalendarDatePicker();
calendarDatePicker.Header = "Enter your date of birth";

Header customization

By using the control’s HeaderTemplate property, you can customize the appearance of the control’s header. The following code sample shows how to use a header template to customize the header.

MainWindow.xaml

<Window
    ...
     xmlns:calendar="using:Syncfusion.UI.Xaml.Calendar">
    <calendar:SfCalendarDatePicker  Width="180" Height="75" >
                <calendar:SfCalendarDatePicker.HeaderTemplate>
                    <DataTemplate>
                        <StackPanel Orientation="Horizontal">
                           <FontIcon FontFamily="Segoe MDL2 Assets" Glyph="&#xED55;"/>
                            <TextBlock Text="Birthday Date" FontSize="14" Margin="5"/>
                        </StackPanel>
                    </DataTemplate>
                </calendar:SfCalendarDatePicker.HeaderTemplate>
    </calendar:SfCalendarDatePicker>
</Window>

Description

The Description support is used to display the content beneath the control as well as to provide guidance on the input that the control expects.

MainWindow.xaml

<Window
    ...
     xmlns:calendar="using:Syncfusion.UI.Xaml.Calendar">
    <calendar:SfCalendarDatePicker x:Name="CalendarDatePicker"
                                  Header="Enter your date of birth"
                                  Width="300"
                                  Height="80"
                                  Description="Candidate should be born between 1990 and 2010."
                                  />
</Window>

MainWindow.xaml.cs

using Syncfusion.UI.Xaml.Calendar;

SfCalendarDatePicker calendarDatePicker = new SfCalendarDatePicker();
calendarDatePicker.Description = "Candidate should be born between 1990 and 2010.";

Setting watermark text

You can prompt the user with some information by using the PlaceholderText property. This will be displayed only when the Calendar Date Picker contains the SelectedDate property as null and the AllowNull property as true. If the AllowNull property is false, then the current system date is updated in the SelectedDate property and displayed instead of the PlaceholderText.

MainWindow.xaml

<Window
    ...
     xmlns:calendar="using:Syncfusion.UI.Xaml.Calendar">
    <calendar:SfCalendarDatePicker Name="sfCalendarDatePicker"
                                   PlaceholderText="Select the Date"
                                   SelectedDate="{x:Null}"
                                   AllowNull="True"
                                    />
</Window>

MainWindow.xaml.cs

using Syncfusion.UI.Xaml.Calendar;

SfCalendarDatePicker sfCalendarDatePicker = new SfCalendarDatePicker();
sfCalendarDatePicker.PlaceholderText = "Select the Date";
sfCalendarDatePicker.SelectedDate = null;
sfCalendarDatePicker.AllowNull = true;

NOTE

Download demo application from GitHub

Selection changed notification

You will be notified when the selected date is changed in the Calendar Date Picker by using the SelectedDateChanged event. The SelectedDateChanged event contains the old and newly selected date in the OldDate and NewDate properties.

• OldDate - Gets the date that was previously selected.
• NewDate - Gets the date that is currently selected.

MainWindow.xaml

<Window
    ...
     xmlns:calendar="using:Syncfusion.UI.Xaml.Calendar">
    <calendar:SfCalendarDatePicker Name="sfCalendarDatePicker"
                                   SelectedDateChanged="SfCalendarDatePicker_SelectedDateChanged"
                                   />
</Window>

MainWindow.xaml.cs

using Syncfusion.UI.Xaml.Calendar;

SfCalendarDatePicker sfCalendarDatePicker = new SfCalendarDatePicker();
sfCalendarDatePicker.SelectedDateChanged += SfCalendarDatePicker_SelectedDateChanged;

You can handle the event as follows:

MainWindow.xaml.cs

using Syncfusion.UI.Xaml.Calendar;

private void SfCalendarDatePicker_SelectedDateChanged(object sender, SelectedDateChangedEventArgs e)
{
    var oldDate = e.OldDate;
    var newDate = e.NewDate;
}

Edit date using free form editing

Since the default value of the EditMode property is Mask, each input number entered in the editor is automatically validated with the DisplayDateFormat’s formats and the proper value is assigned to the current field. Then, the focus will move to the next input field of the date format.

If you want to perform the validation after the user has completely entered their date inputs, set the EditMode property value as Normal. Then, the entered date value is validated with the DisplayDateFormat property value by pressing the Enter key or when focus is lost. If the entered value does not suit the DisplayDateFormat property, the previously selected date value is set to the SelectedDate property.

MainWindow.xaml

<Window
    ...
     xmlns:calendar="using:Syncfusion.UI.Xaml.Calendar">
    <calendar:SfCalendarDatePicker x:Name="sfCalendarDatePicker"
                                   EditMode="Normal"
                                   />
</Window>

MainWindow.xaml.cs

using Syncfusion.UI.Xaml.Calendar;

SfCalendarDatePicker sfCalendarDatePicker = new SfCalendarDatePicker();
sfCalendarDatePicker.EditMode = DateTimeEditMode.Normal;

NOTE

Download demo application from GitHub.

Cancel a date that is being changed

The SelectedDateChanging event will be triggered as soon as a date is selected but before the SelectedDate property is updated. If the change is considered invalid, it can be canceled. The SelectedDateChanging event contains the following properties:

• OldDate - Gets the date that was previously selected.
• NewDate - Gets the date that is currently selected.
• Cancel - Gets or sets whether to cancel the selected date value update.

Users are restricted from selecting a blackout date from the drop-down menu, but you can provide text input through the editor. Because selecting a blackout date leads to a crash, you can cancel the change using the SelectedDateChanging event.

NOTE

SelectedDateChanging event is called before the SelectedDateChanged event, when a date is selected.

MainWindow.xaml

<Window
    ...
     xmlns:calendar="using:Syncfusion.UI.Xaml.Calendar">
    <calendar:SfCalendarDatePicker Height="30" Width="250"
                                   x:Name="SfCalendarDatePicker"
                                   SelectedDateChanging="SfCalendarDatePicker_DateChanging" />
</Window>

MainWindow.xaml.cs

using Syncfusion.UI.Xaml.Calendar;

SfCalendarDatePicker sfCalendarDatePicker = new SfCalendarDatePicker();
sfCalendarDatePicker.SelectedDateChanging += SfCalendarDatePicker_DateChanging;

You can handle the event as follows:

MainWindow.xaml.cs

using Syncfusion.UI.Xaml.Calendar;

 private void SfCalendarDatePicker_DateChanging(object sender, Syncfusion.UI.Xaml.Editors.DateChangingEventArgs e)
{
    var OldDate = e.OldDate;
    var NewDate = e.NewDate;

    //Cancel Selected date update
    e.Cancel = true;
}

Hide the drop-down button

You can hide the drop-down button in Calendar Date Picker by setting the ShowDropDownButton property value as false. The default value of ShowDropDownButton property is true.

NOTE

When the drop-down button is hidden, you can still open the drop-down calendar using ALT + DownArrow keyboard shortcut.

MainWindow.xaml

<Window
    ...
     xmlns:calendar="using:Syncfusion.UI.Xaml.Calendar">
    <calendar:SfCalendarDatePicker
                                   x:Name="sfCalendarDatePicker"
                                   ShowDropDownButton="False"  />
</Window>

MainWindow.xaml.cs

using Syncfusion.UI.Xaml.Calendar;

SfCalendarDatePicker sfCalendarDatePicker = new SfCalendarDatePicker();
sfCalendarDatePicker.ShowDropDownButton = false;

NOTE

Download demo application from GitHub.

Show submit button

If you want to select the date from the drop-down calendar only by clicking the Ok button, set the ShowSubmitButtons property value as true. The default value of the ShowSubmitButtons property is false.

NOTE

When the submit buttons are visible, the SelectedDate property will be updated only after choosing the date from the drop-down and clicking the Ok button.

MainWindow.xaml

<Window
    ...
     xmlns:calendar="using:Syncfusion.UI.Xaml.Calendar">
    <calendar:SfCalendarDatePicker
                                   x:Name="sfCalendarDatePicker"
                                   ShowSubmitButtons="true" />
</Window>

MainWindow.xaml.cs

using Syncfusion.UI.Xaml.Calendar;

SfCalendarDatePicker sfCalendarDatePicker = new SfCalendarDatePicker();
sfCalendarDatePicker.ShowSubmitButtons = true;

NOTE

Download demo application from GitHub.

Restrict selection

You can restrict users from:

• Selecting a date within a specific minimum and maximum range using the MinDate and MaxDate properties.
• Selecting a date from blocked dates using the BlackoutDates property.
• Selecting a date from a specifically blocked set of dates (example: blocking weekend dates) using the CalendarItemPrepared event.

For further details, refer to Date Selection and Restriction.

Navigation between views

• You can navigate between month, year, decade, and century views in the Calendar Date Picker control.
• You can also restrict users from navigating between specific views only (month and year selection for credit card) using the MinDisplayMode and MaxDisplayMode properties.

For further details, refer to Navigation.