Getting Started with WinUI Calendar DatePicker (Calendar Date Picker)

5 Jan 2021 / 17 minutes to read

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

Structure of CalendarDatePicker control

Structure of WinUI CalendarDatePicker control

Creating an application with WinUI CalendarDatePicker

  1. Create a simple project using the instructions given in the Getting Started with your first WinUI app documentation.
  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 CalendarDatePicker 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);
        }
    }
}

CalendarDatePicker control added in the application

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, CalendarDatePicker will automatically assign the current system date as SelectedDate.

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

CalendarDatePicker displaying the selected date

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();

CalendarDatePicker displaying selected value

NOTE

Download demo application from GitHub

Setting null value

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

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

CalendarDatePicker displaying 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 CalendarDatePicker contains the SelectedDate property as null and AllowNullValue property as true. If AllowNullValue 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}"
                               AllowNullValue="True"
                               Name="sfCalendarDatePicker" />
SfCalendarDatePicker sfCalendarDatePicker= new SfCalendarDatePicker();
sfCalendarDatePicker.PlaceHolderText = "Select the Date";
sfCalendarDatePicker.SelectedDate = null;
sfCalendarDatePicker.AllowNullValue = true;

CalendarDatePicker displaying watermark text

NOTE

Download demo application from GitHub

Restrict date selection

You can restrict the users from selecting a date within the particular range by specifying MinDate and MaxDate properties. The default value of MinDate property is 1/1/1920 12:00:00 AM +00:00 and MaxDate property is 12/31/2120 11:59:59 PM +00:00.

<calendar:Calendar x:Name="sfCalendarDatePicker"/>
SfCalendarDatePicker sfCalendarDatePicker = new SfCalendarDatePicker();
sfCalendarDatePicker.MinDate = new DateTimeOffset(new DateTime(2021, 01, 5));
sfCalendarDatePicker.MaxDate = new DateTimeOffset(new DateTime(2021, 01, 24));

CalendarDatePicker restrict the date selection with particular range

NOTE

Download demo application from GitHub

Block dates using BlackoutDates

If you want to block particular dates from the date selection, add that dates into the BlackoutDates collection. You can add more block out dates to the BlackoutDates collection. The default value of BlackoutDates property is null.

public class ViewModel
{       
    public DateTimeOffsetCollection BlockedDates { get; set; }
    public ViewModel()
    {
        BlockedDates = new DateTimeOffsetCollection();
        BlockedDates.Add(new DateTimeOffset(new DateTime(2021, 1, 17)));
        BlockedDates.Add(new DateTimeOffset(new DateTime(2021, 1, 4)));
        BlockedDates.Add(new DateTimeOffset(new DateTime(2021, 2, 5)));
        BlockedDates.Add(new DateTimeOffset(new DateTime(2021, 2, 6)));
        BlockedDates.Add(new DateTimeOffset(new DateTime(2021, 1, 9)));
        BlockedDates.Add(new DateTimeOffset(new DateTime(2021, 3, 11)));
        BlockedDates.Add(new DateTimeOffset(new DateTime(2021, 1, 13)));
        BlockedDates.Add(new DateTimeOffset(new DateTime(2021, 4, 14)));
        BlockedDates.Add(new DateTimeOffset(new DateTime(2021, 1, 18)));
        BlockedDates.Add(new DateTimeOffset(new DateTime(2021, 5, 19)));
        BlockedDates.Add(new DateTimeOffset(new DateTime(2021, 1, 26)));
        BlockedDates.Add(new DateTimeOffset(new DateTime(2021, 6, 29)));
        BlockedDates.Add(new DateTimeOffset(new DateTime(2021, 1, 31)));
        BlockedDates.Add(new DateTimeOffset(new DateTime(2021, 1, 27)));
    }
}
<calendar:SfCalendarDatePicker BlackoutDates="{Binding BlockedDates}" 
                     x:Name="sfCalendarDatePicker">
    <calendar:SfCalendarDatePicker.DataContext>
        <local:ViewModel/>
    </calendar:SfCalendarDatePicker.DataContext>
</calendar:SfCalendarDatePicker>
sfCalendarDatePicker.DataContext = new ViewModel();
sfCalendarDatePicker.BlackoutDates = (sfCalendarDatePicker.DataContext as ViewModel).BlockedDates;

CalendarDatePicker blocks the particular dates from selection

NOTE

Download demo application from GitHub

Disable/block all weekends

You can prevent the users from selecting weekend days or any other dates by handling the CalendarItemPrepared event and setting ItemInfo.IsBlackout property value as true for that specific dates.

<calendar:SfCalendarDatePicker x:Name="sfCalendarDatePicker"
                               CalendarItemPrepared="SfCalendarDatePicker_CalendarItemPrepared"/>
SfCalendarDatePicker sfCalendarDatePicker = new SfCalendarDatePicker();
sfCalendarDatePicker.CalendarItemPrepared += SfCalendarDatePicker_CalendarItemPrepared;

You can handle the event as follows:

private void SfCalendarDatePicker_CalendarItemPrepared(object sender, CalendarItemPreparedEventArgs e)
{
    //Block all weekend days
    if (e.ItemInfo.ItemType == CalendarItemType.Day &&
        (e.ItemInfo.Date.DayOfWeek == DayOfWeek.Saturday ||
        e.ItemInfo.Date.DayOfWeek == DayOfWeek.Sunday))
    {
        e.ItemInfo.IsBlackout = true;
    }
}

CalendarDatePicker restrict the weekend dates from selection

NOTE

Download demo application from GitHub

Selected date changed notification

You will be notified when selected date changed in CalendarDatePicker 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;
}

Change date display format

You can edit and display the selected date with various formatting like date, month and year formats by using the FormatString property. The default value of FormatString property is d.

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

CalendarDatePicker selected date with month format

NOTE

Download demo application from GitHub

Change date format for Spinner

You can use different date formats such as abbreviated or full name for a day, month, week names or header name of month and year in drop-down spinner by using the DateFormat, MonthFormat, DayOfWeekFormat and HeaderFormatInMonthView properties.

NOTE

Refer DateTimeFormatter page to get more date formatting.

<calendar:SfCalendarDatePicker DateFormat="{}{day.integer(2)}"
                               MonthFormat="{}{month.full}"
                               DayOfWeekFormat="{}{dayofweek.abbreviated(3)}"
                               HeaderFormatInMonthView="{}{month.abbreviated} {year.abbreviated}‎"
                               x:Name="sfCalendarDatePicker"/>
SfCalendarDatePicker sfCalendarDatePicker = new SfCalendarDatePicker();
sfCalendarDatePicker.DateFormat = "{day.integer(2)}";
sfCalendarDatePicker.MonthFormat = "{month.full}";
sfCalendarDatePicker.DayOfWeekFormat = "{dayofweek.abbreviated(3)}";
sfCalendarDatePicker.HeaderFormatInMonthView = "{month.abbreviated} {year.abbreviated}‎";

Displaying full month and abbreviated year format in WinUI CalendarDatePicker.

NOTE

Download demo application from GitHub

Edit date using free form editing

By default, user entering each input numbers are automatically validated with the FormatString’s formats and assigned the proper value for current field, then it will move to next input field of the date format.

If you want to perform the validation after the user completely entering their date inputs, use the EditMode property value as Normal. Then the entered date value is validated with the FormatString property value by pressing the Enter key or lost focus. If entered value is not suit with FormatString 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;

CalendarDatePicker enables free form editing to select date

NOTE

Download demo application from GitHub

You can easily navigate to the month, year, decade, or century views to select different dates in the drop-down spinner by repeatedly clicking the header button. Initially month view is loaded. If you want to change the initial view, use DisplayMode property.

You can restrict navigation within a minimum and maximum views by using MinDisplayMode and MaxDisplayMode properties. This will be useful when your date range is smaller and you don’t want to show century view.

<calendar:SfCalendarDatePicker x:Name="sfCalendarDatePicker"
                               MinDisplayMode="Month"
                               MaxDisplayMode="Century"
                               DisplayMode="Month"/>
SfCalendarDatePicker sfCalendarDatePicker = new SfCalendarDatePicker();
sfCalendarDatePicker.MinDisplayMode = CalendarDisplayMode.Month;
sfCalendarDatePicker.MaxDisplayMode = CalendarDisplayMode.Century;
sfCalendarDatePicker.DisplayMode = CalendarDisplayMode.Month;

Navigation between month and century view in WinUI CalendarDatePicker

NOTE

Download demo application from GitHub

Calendar types

The CalendarDatePicker control supports different type of calendars such as Gregorian, Julian, Hebrew, etc. You can change the calendar type by using CalendarIdentifier property. The default value of CalendarIdentifier property is GregorianCalendar.

NOTE

Refer CalendarIdentifiers page to get more calendar types.

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

Displaying Hebrew-type WinUI CalendarDatePicker.

NOTE

Download demo application from GitHub

Culture support

If you want to localize the drop-down spinner calendar, use the Language property. The default value of Language property is en-US.

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

Displaying arabic cultured WinUI CalendarDatePicker.

NOTE

Download demo application from GitHub