Getting Started with WinUI Calendar Date Picker

2 Sep 202111 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

Overview of WinUI CalendarDatePicker

Creating an application with WinUI Calendar Date Picker

  1. Create a WinUI 3 desktop app for C# and .NET 5.
  2. Add reference to Syncfusion.Calendar.WinUI NuGet.
  3. Import the control namespace Syncfusion.UI.Xaml.Calendar in XAML or C# code.
  4. Initialize the SfCalendarDatePicker control.
<Page
    x:Class="GettingStarted.MainPage"
    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"
    Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
    <Grid Name="grid">
        <!--Adding Calendar Date Picker control -->
        <calendar:SfCalendarDatePicker Name="sfCalendarDatePicker"/>
    </Grid>
</Page>
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 MainPage : Page
    {
        public MainPage()
        {
            this.InitializeComponent();
            // Creating an instance of the Calendar control
            SfCalendarDatePicker sfCalendarDatePicker = new SfCalendarDatePicker();

            grid.Children.Add(sfCalendarDatePicker);
        }
    }
}

WinUI CalendarDatePicker control

NOTE

Download demo application from GitHub

Select the date programmatically

You can set or change the selected date programmatically by using SelectedDate property. If you not assign any value for the SelectedDate property, Calendar Date Picker will automatically assign the current system date as SelectedDate.

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

Changing Selected Date Programmatically in WinUI CalendarDatePicker

NOTE

Download demo application from GitHub

Select date interactively

You can change the selected date interactively by enter the date value using keyboard or select from drop down calendar spinner. You can get the selected date from the SelectedDate property.

<calendar:SfCalendarDatePicker Name="sfCalendarDatePicker" />
SfCalendarDatePicker sfCalendarDatePicker= new SfCalendarDatePicker();

Date Selection in WinUI CalendarDatePicker

NOTE

Download demo application from GitHub

Setting null value

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

<calendar:SfCalendarDatePicker SelectedDate="{x:Null}"
                               AllowNull="True"
                               Name="sfCalendarDatePicker" />
SfCalendarDatePicker sfCalendarDatePicker= new SfCalendarDatePicker();
sfCalendarDatePicker.SelectedDate = null;
sfCalendarDatePicker.AllowNull = true;

WinUI CalendarDatePicker with Null Value

NOTE

Download demo application from GitHub

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 AllowNull property as true. If AllowNull property is false, then the current system date is updated in SelectedDate property and displayed instead of PlaceholderText.

<calendar:SfCalendarDatePicker PlaceholderText="Select the Date"
                               SelectedDate="{x:Null}"
                               AllowNull="True"
                               Name="sfCalendarDatePicker" />
SfCalendarDatePicker sfCalendarDatePicker= new SfCalendarDatePicker();
sfCalendarDatePicker.PlaceholderText = "Select the Date";
sfCalendarDatePicker.SelectedDate = null;
sfCalendarDatePicker.AllowNull = true;

Calendar Date Picker with Watermark Text

NOTE

Download demo application from GitHub

Selection changed notification

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

  • OldDate - Gets a date which is previously selected.
  • NewDate - Gets a date which is currently selected.
<calendar:SfCalendarDatePicker SelectedDateChanged="SfCalendarDatePicker_SelectedDateChanged" 
                               Name="sfCalendarDatePicker"/>
SfCalendarDatePicker sfCalendarDatePicker = new SfCalendarDatePicker();
sfCalendarDatePicker.SelectedDateChanged += SfCalendarDatePicker_SelectedDateChanged;

You can handle the event as follows:

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 EditMode property is Mask, each input numbers entered in editor are automatically validated with the DisplayDateFormat’s formats and the proper value is assigned in current field. Then focus will move to next input field of the date format.

If you want to perform the validation after the user 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 lost focus. If entered value is not suit with DisplayDateFormat property, the previously selected date value sets to SelectedDate property.

<calendar:SfCalendarDatePicker EditMode="Normal"
                               x:Name="sfCalendarDatePicker" />
SfCalendarDatePicker sfCalendarDatePicker = new SfCalendarDatePicker();
sfCalendarDatePicker.EditMode = DateTimeEditingMode.Normal;

Editing in WinUI CalendarDatePicker

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 SelectedDate property is updated. If the change is considered invalid, it can be canceled. The SelectedDateChanging event contains the following properties.

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

Users are restricted to select a blackout date from dropdown, however user can give text input through editor. As selecting a blackout date leads to crash, we can cancel the change using SelectedDateChanging event.

NOTE

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

<calendar:SfCalendarDatePicker Height="30" Width="250" 
                               x:Name="SfCalendarDatePicker"
                               SelectedDateChanging="SfCalendarDatePicker_DateChanging" />
SfCalendarDatePicker sfCalendarDatePicker = new SfCalendarDatePicker();
sfCalendarDatePicker.SelectedDateChanging += SfCalendarDatePicker_DateChanging;

You can handle the event as follows:

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 dropdown button

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

NOTE

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

<calendar:SfCalendarDatePicker ShowDropDownButton="False" 
                               x:Name="sfCalendarDatePicker"/>
SfCalendarDatePicker sfCalendarDatePicker = new SfCalendarDatePicker();
sfCalendarDatePicker.ShowDropDownButton = false;

Hide Dropdown Button in WinUI CalendarDatePicker

NOTE

Download demo application from GitHub

Show submit button

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

NOTE

When the submit buttons are hidden, SelectedDate property will be updated as soon you choose start and end date from dropdown.

<calendar:SfCalendarDatePicker ShowSubmitButtons="true"
                               x:Name="sfCalendarDatePicker"/>
SfCalendarDatePicker sfCalendarDatePicker = new SfCalendarDatePicker();
sfCalendarDatePicker.ShowSubmitButtons = true;

WinUI CalendarDatePicker with Submit and Cancel Buttons

NOTE

Download demo application from GitHub

Restrict selection

You can restrict users from:

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

For further details refer Date Selection and Restriction.

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

WinUI CalendarDatePicker displays Navigation View

For further details refer Navigation.