menu

WinUI

  • Code Examples
  • Upgrade Guide
  • User Guide
  • Demos
  • Support
  • Forums
  • Download
Class SfCalendarDatePicker - WinUI API Reference | Syncfusion

    Show / Hide Table of Contents

    Class SfCalendarDatePicker

    Represent a control that allows users to pick a date from the drop-down list and edit the date using a masked input.

    Inheritance
    System.Object
    SfDropDownBase
    DateTimePickerBase
    SfCalendarDatePicker
    Implements
    System.IDisposable
    Inherited Members
    DateTimePickerBase.AllowNull
    DateTimePickerBase.AllowNullProperty
    DateTimePickerBase.Description
    DateTimePickerBase.DescriptionProperty
    DateTimePickerBase.EditMode
    DateTimePickerBase.EditModeProperty
    DateTimePickerBase.Header
    DateTimePickerBase.HeaderProperty
    DateTimePickerBase.HeaderTemplate
    DateTimePickerBase.HeaderTemplateProperty
    DateTimePickerBase.OnGotFocus(RoutedEventArgs)
    DateTimePickerBase.OnKeyDown(KeyRoutedEventArgs)
    DateTimePickerBase.OnKeyUp(KeyRoutedEventArgs)
    DateTimePickerBase.OnPointerEntered(PointerRoutedEventArgs)
    DateTimePickerBase.OnPointerExited(PointerRoutedEventArgs)
    DateTimePickerBase.OnPointerPressed(PointerRoutedEventArgs)
    DateTimePickerBase.ShowClearButton
    DateTimePickerBase.ShowClearButtonProperty
    SfDropDownBase.CloseDropDown()
    SfDropDownBase.Content
    SfDropDownBase.ContentProperty
    SfDropDownBase.ContentTemplate
    SfDropDownBase.ContentTemplateProperty
    SfDropDownBase.Dispose()
    SfDropDownBase.DropDownButtonTemplate
    SfDropDownBase.DropDownButtonTemplateProperty
    SfDropDownBase.DropDownClosed
    SfDropDownBase.DropDownHeight
    SfDropDownBase.DropDownHeightProperty
    SfDropDownBase.DropDownMode
    SfDropDownBase.DropDownModeProperty
    SfDropDownBase.DropDownOpened
    SfDropDownBase.DropDownPlacement
    SfDropDownBase.DropDownPlacementProperty
    SfDropDownBase.IsOpen
    SfDropDownBase.IsOpenProperty
    SfDropDownBase.OnDeclineButtonClicked()
    SfDropDownBase.OnPrimaryButtonClicked()
    SfDropDownBase.OpenDropDown()
    SfDropDownBase.ShowDropDownButton
    SfDropDownBase.ShowDropDownButtonProperty
    SfDropDownBase.ShowSubmitButtons
    SfDropDownBase.ShowSubmitButtonsProperty
    Namespace: Syncfusion.UI.Xaml.Calendar
    Assembly: Syncfusion.Calendar.WinUI.dll
    Syntax
    public class SfCalendarDatePicker : DateTimePickerBase, IDisposable
    Examples
    <calendar:SfCalendarDatePicker x:Name="calendarDatePicker" FirstDayOfWeek="Sunday" PlaceHolderText="Select a date" />

    Constructors

    SfCalendarDatePicker()

    Initializes a new instance of the SfCalendarDatePicker class.

    Declaration
    public SfCalendarDatePicker()
    Examples
    <calendar:SfCalendarDatePicker x:Name="calendarDatePicker" FirstDayOfWeek="Sunday" PlaceHolderText="Select a date" />

    Fields

    BlackoutDatesProperty

    Identifies BlackoutDates dependency property.

    Declaration
    public static readonly DependencyProperty BlackoutDatesProperty
    Field Value
    Type Description
    Microsoft.UI.Xaml.DependencyProperty

    The identifier for the BlackoutDates dependency property.

    CalendarIdentifierProperty

    Identifies CalendarIdentifier dependency property.

    Declaration
    public static readonly DependencyProperty CalendarIdentifierProperty
    Field Value
    Type Description
    Microsoft.UI.Xaml.DependencyProperty

    The identifier for the CalendarIdentifier dependency property.

    DayFormatProperty

    Identifies DayFormat dependency property.

    Declaration
    public static readonly DependencyProperty DayFormatProperty
    Field Value
    Type Description
    Microsoft.UI.Xaml.DependencyProperty

    The identifier for the DayFormat dependency property.

    DayOfWeekFormatProperty

    Identifies DayOfWeekFormat dependency property.

    Declaration
    public static readonly DependencyProperty DayOfWeekFormatProperty
    Field Value
    Type Description
    Microsoft.UI.Xaml.DependencyProperty

    The identifier for the DayOfWeekFormat dependency property.

    DisplayDateFormatProperty

    Identifies the DisplayDateFormat dependency property.

    Declaration
    public static readonly DependencyProperty DisplayDateFormatProperty
    Field Value
    Type Description
    Microsoft.UI.Xaml.DependencyProperty

    The identifier for the DisplayDateFormat dependency property.

    DisplayModeProperty

    Identifies DisplayMode dependency property.

    Declaration
    public static readonly DependencyProperty DisplayModeProperty
    Field Value
    Type Description
    Microsoft.UI.Xaml.DependencyProperty

    The identifier for the DisplayMode dependency property.

    DropDownWidthProperty

    Identifies DropDownWidth dependency property.

    Declaration
    public static readonly DependencyProperty DropDownWidthProperty
    Field Value
    Type Description
    Microsoft.UI.Xaml.DependencyProperty

    The identifier for the DropDownWidth dependency property.

    FirstDayOfWeekProperty

    Identifies FirstDayOfWeek dependency property.

    Declaration
    public static readonly DependencyProperty FirstDayOfWeekProperty
    Field Value
    Type Description
    Microsoft.UI.Xaml.DependencyProperty

    The identifier for the FirstDayOfWeek dependency property.

    MaxDateProperty

    Identifies the MaxDate dependency property.

    Declaration
    public static readonly DependencyProperty MaxDateProperty
    Field Value
    Type Description
    Microsoft.UI.Xaml.DependencyProperty

    The identifier for the MaxDate dependency property.

    MaxDisplayModeProperty

    Identifies MaxDisplayMode dependency property.

    Declaration
    public static readonly DependencyProperty MaxDisplayModeProperty
    Field Value
    Type Description
    Microsoft.UI.Xaml.DependencyProperty

    The identifier for the MaxDisplayMode dependency property.

    MinDateProperty

    Identifies the MinDate dependency property.

    Declaration
    public static readonly DependencyProperty MinDateProperty
    Field Value
    Type Description
    Microsoft.UI.Xaml.DependencyProperty

    The identifier for the MinDate dependency property.

    MinDisplayModeProperty

    Identifies MinDisplayMode dependency property.

    Declaration
    public static readonly DependencyProperty MinDisplayModeProperty
    Field Value
    Type Description
    Microsoft.UI.Xaml.DependencyProperty

    The identifier for the MinDisplayMode dependency property.

    MonthFormatProperty

    Identifies MonthFormat dependency property.

    Declaration
    public static readonly DependencyProperty MonthFormatProperty
    Field Value
    Type Description
    Microsoft.UI.Xaml.DependencyProperty

    The identifier for the MonthFormat dependency property.

    MonthHeaderFormatProperty

    Identifies MonthHeaderFormat dependency property.

    Declaration
    public static readonly DependencyProperty MonthHeaderFormatProperty
    Field Value
    Type Description
    Microsoft.UI.Xaml.DependencyProperty

    The identifier for the MonthHeaderFormat dependency property.

    NumberOfWeeksInViewProperty

    Identifies NumberOfWeeksInView dependency property.

    Declaration
    public static readonly DependencyProperty NumberOfWeeksInViewProperty
    Field Value
    Type Description
    Microsoft.UI.Xaml.DependencyProperty

    The identifier for the NumberOfWeeksInView dependency property.

    OutOfScopeVisibilityProperty

    Identifies OutOfScopeVisibility dependency property.

    Declaration
    public static readonly DependencyProperty OutOfScopeVisibilityProperty
    Field Value
    Type Description
    Microsoft.UI.Xaml.DependencyProperty

    The identifier for the OutOfScopeVisibility dependency property.

    PlaceholderTextProperty

    Identifies the PlaceholderText dependency property.

    Declaration
    public static readonly DependencyProperty PlaceholderTextProperty
    Field Value
    Type Description
    Microsoft.UI.Xaml.DependencyProperty

    The identifier for the PlaceholderText dependency property.

    SelectedDateProperty

    Identifies the SelectedDate dependency property.

    Declaration
    public static readonly DependencyProperty SelectedDateProperty
    Field Value
    Type Description
    Microsoft.UI.Xaml.DependencyProperty

    The identifier for the SelectedDate dependency property.

    SelectionHighlightModeProperty

    Identifies SelectionHighlightMode dependency property.

    Declaration
    public static readonly DependencyProperty SelectionHighlightModeProperty
    Field Value
    Type Description
    Microsoft.UI.Xaml.DependencyProperty

    The identifier for the SelectionHighlightMode dependency property.

    SelectionShapeProperty

    Identifies SelectionShape dependency property.

    Declaration
    public static readonly DependencyProperty SelectionShapeProperty
    Field Value
    Type Description
    Microsoft.UI.Xaml.DependencyProperty

    The identifier for the SelectionShape dependency property.

    ShowWeekNumbersProperty

    Identifies ShowWeekNumbers dependency property.

    Declaration
    public static readonly DependencyProperty ShowWeekNumbersProperty
    Field Value
    Type Description
    Microsoft.UI.Xaml.DependencyProperty

    The identifier for the ShowWeekNumbers dependency property.

    WeekNumberFormatProperty

    Identifies WeekNumberFormat dependency property.

    Declaration
    public static readonly DependencyProperty WeekNumberFormatProperty
    Field Value
    Type Description
    Microsoft.UI.Xaml.DependencyProperty

    The identifier for the WeekNumberFormat dependency property.

    WeekNumberRuleProperty

    Identifies WeekNumberRule dependency property.

    Declaration
    public static readonly DependencyProperty WeekNumberRuleProperty
    Field Value
    Type Description
    Microsoft.UI.Xaml.DependencyProperty

    The identifier for the WeekNumberRule dependency property.

    Properties

    BlackoutDates

    Gets or sets the collection of restricted dates, that are not allowed to select.

    Declaration
    public DateTimeOffsetCollection BlackoutDates { get; set; }
    Property Value
    Type Description
    DateTimeOffsetCollection

    The default value is null.

    Remarks

    SfCalendarDatePicker disables the date, if the date is present in blackout dates collection.

    Examples
    • XAML
    • C#

    Below example shows how to set blackout dates in SfCalendarDatePicker.

    <Page.DataContext>
      <local:ViewModel x:Name="viewModel" />
     </Page.DataContext>
     <Grid>
         <calendar:SfCalendarDatePicker BlackoutDates = "{x:Bind viewModel.BlackOutDates}" FirstDayOfWeek="Sunday"/>
     </Grid>

    Below example shows how to set blackout dates in SfCalendarDatePicker.

    public class ViewModel
    {
      public DateTimeOffsetCollection BlackOutDates;
        public ViewModel()
       {
         BlackOutDates = new DateTimeOffsetCollection();
         BlackOutDates.Add(new DateTimeOffset(DateTime.Now.AddDays(-2)));
         BlackOutDates.Add(new DateTimeOffset(DateTime.Now.AddDays(2)));
       }
    }

    CalendarIdentifier

    Gets or sets the calendar system to use.

    Declaration
    public string CalendarIdentifier { get; set; }
    Property Value
    Type Description
    System.String

    The default value is GregorianCalendar.

    Remarks

    All calendar types are supported except JapaneseCalendar and Lunar type calendars.

    Examples
    calendarDatePicker.CalendarIdentifier = Windows.Globalization.CalendarIdentifiers.Hebrew;

    DayFormat

    Gets or sets the date format in month view.

    Declaration
    public string DayFormat { get; set; }
    Property Value
    Type Description
    System.String

    Default value is {day.integer}.

    Examples
    • XAML
    • C#

    This example shows how to set date format in XAML.

    <calendar:SfCalendarDatePicker x:Name="calendarDatePicker"  DateFormat="{}{day.integer(2)}" />

    This example shows how to set date format in C#.

    calendarDatePicker.DateFormat = "{day.integer(2)}";

    DayOfWeekFormat

    Gets or sets the display format for the day name of the week headers in month view.

    Declaration
    public string DayOfWeekFormat { get; set; }
    Property Value
    Type Description
    System.String

    Default value is {dayofweek.abbreviated(2)}.

    Examples
    • XAML
    • C#

    This example shows how to set days name format in XAML.

    <calendar:SfCalendarDatePicker x:Name="calendarDatePicker" DayOfWeekFormat="{}{dayofweek.abbreviated(3)}" />

    This example shows how to set days name format in C#.

    calendarDatePicker.MonthFormat = "{dayofweek.abbreviated(3)}";

    DisplayDateFormat

    Gets or sets the display or editing format of SelectedDate.

    Declaration
    public string DisplayDateFormat { get; set; }
    Property Value
    Type Description
    System.String

    The default value is d.

    Examples
    <calendar:SfCalendarDatePicker x:Name="calendarDatePicker"
                                   FormatString="MM/yyyy"
                                  />
    public MainPage()
    {
        this.InitializeComponent();
        SfCalendarDatePicker calendarDatePicker = new SfCalendarDatePicker();
        calendarDatePicker.FormatString = "MM/yyyy";
    }

    DisplayMode

    Gets or sets a value that indicates the active view (month, year, decade or century) to be displayed while loading dropdown calendar. Based on MinDisplayMode, date selection is performed.

    Declaration
    public CalendarDisplayMode DisplayMode { get; set; }
    Property Value
    Type Description
    CalendarDisplayMode

    The default value is Month.

    Remarks

    DisplayMode value should be within MinDisplayMode and MaxDisplayMode properties views.

    DropDownWidth

    Gets or sets the width of the drop down popup in SfCalendarDatePicker control.

    Declaration
    public double DropDownWidth { get; set; }
    Property Value
    Type Description
    System.Double

    The default value is Auto.

    Remarks

    When DropDownWidth is auto, popup width changes based on size required by Content.

    FirstDayOfWeek

    Gets or sets a value that indicates which day is shown as the first day of the week.

    Declaration
    public FirstDayOfWeek FirstDayOfWeek { get; set; }
    Property Value
    Type Description
    FirstDayOfWeek

    The default value is Auto.

    Remarks

    Auto will select the FirstDayOfWeek based on current culture.

    MaxDate

    Gets or sets the last date to display.

    Declaration
    public DateTimeOffset MaxDate { get; set; }
    Property Value
    Type Description
    System.DateTimeOffset

    The default value is 12/31/2120.

    Remarks

    MaxDate value should be greater than MinDate.

    Exceptions
    Type Condition
    System.InvalidOperationException

    MaxDate value should not be less than MinDate value.

    MaxDisplayMode

    Gets or sets a value indicating the maximum view that can be navigated.

    Declaration
    public CalendarDisplayMode MaxDisplayMode { get; set; }
    Property Value
    Type Description
    CalendarDisplayMode

    The default value is Century.

    Remarks

    MaxDisplayMode value should be greater than MinDisplayMode value.

    Exceptions
    Type Condition
    System.InvalidOperationException

    MaxDisplayMode value should not be less than MinDisplayMode value.

    MinDate

    Gets or sets the first date to display.

    Declaration
    public DateTimeOffset MinDate { get; set; }
    Property Value
    Type Description
    System.DateTimeOffset

    The default value is 1/1/1920.

    Remarks

    MinDate value should be less than MaxDate.

    Exceptions
    Type Condition
    System.InvalidOperationException

    MinDate value should not be greater than MaxDate value.

    MinDisplayMode

    Gets or sets a value indicating the minimum view that can be navigated.

    Declaration
    public CalendarDisplayMode MinDisplayMode { get; set; }
    Property Value
    Type Description
    CalendarDisplayMode

    The default value is Month.

    Remarks

    MinDisplayMode value should be less than MaxDisplayMode value.

    Exceptions
    Type Condition
    System.InvalidOperationException

    MinDisplayMode value should not be greater than MaxDisplayMode value.

    MonthFormat

    Gets or sets the month format in year view.

    Declaration
    public string MonthFormat { get; set; }
    Property Value
    Type Description
    System.String

    Default value is {month.abbreviated}.

    Examples
    • XAML
    • C#

    This example shows how to set month format in XAML.

    <calendar:SfCalendarDatePicker x:Name="calendarDatePicker" MonthFormat="{}{month.full}" />

    This example shows how to set month format in C#.

    calendarDatePicker.MonthFormat = "{month.full}";

    MonthHeaderFormat

    Gets or sets header format in month view.

    Declaration
    public string MonthHeaderFormat { get; set; }
    Property Value
    Type Description
    System.String

    Default value is month year.

    Examples
    • XAML
    • C#

    This example shows how to set days name format in XAML.

    <calendar:SfCalendarDatePicker x:Name="calendarDatePicker" MonthHeaderFormat="{}{month.abbreviated} {year.abbreviated}" />

    This example shows how to set month header format in C#.

    calendarDatePicker.MonthHeaderFormat = "{month.abbreviated} {year.abbreviated}";

    NumberOfWeeksInView

    Gets or sets the number of weeks that is shown in month view.

    Declaration
    public int NumberOfWeeksInView { get; set; }
    Property Value
    Type Description
    System.Int32

    The default value is 6.

    OutOfScopeVisibility

    Gets or sets a value indicating the dates that falls out of current calendar scope is rendered.

    Declaration
    public OutOfScopeVisibility OutOfScopeVisibility { get; set; }
    Property Value
    Type Description
    OutOfScopeVisibility

    The default value is Enabled.

    Remarks

    When OutOfScopeVisibility value is Disabled, then the out-of-scope calendar items are displayed in same appearance as normal items. When OutOfScopeVisibility value is Enabled, then the out-of-scope calendar items are shown with a unique foreground color. When OutOfScopeVisibility value is Hidden, then the out-of-scope calendar items will not be displayed.

    PlaceholderText

    Gets or sets the text displayed in the editor textbox.

    Declaration
    public string PlaceholderText { get; set; }
    Property Value
    Type Description
    System.String

    The default value is "Select a date".

    Remarks

    A string value that specifies the string displayed in the editor textbox when the SelectedDate is set to null.

    SelectedDate

    Gets or sets the currently selected date for SfCalendarDatePicker.

    Declaration
    public Nullable<DateTimeOffset> SelectedDate { get; set; }
    Property Value
    Type Description
    System.Nullable<System.DateTimeOffset>

    The default value is null.

    Remarks

    SelectedDateChanged event is invoked, when selected date is changed. SelectedDate will be displayed in editor textbox SfCalendarDatePicker.

    SelectionHighlightMode

    Gets or sets a value on how to highlight the selected date or dates.

    Declaration
    public SelectionHighlightMode SelectionHighlightMode { get; set; }
    Property Value
    Type Description
    SelectionHighlightMode

    The default value is Outline.

    Remarks

    When value is Outline, border of selected date is highlighted and background of today date is highlighted. When value is Filled, background of selected date is highlighted and border of today date is highlighted.

    SelectionShape

    Gets or sets a value to change the shape of selected dates.

    Declaration
    public SelectionShape SelectionShape { get; set; }
    Property Value
    Type Description
    SelectionShape

    The default value is Circle.

    Remarks

    When value is Rectangle the selected date cells are highlighted in rectangle shape. When value is Circle the selected date cells are highlighted in circle shape.

    ShowWeekNumbers

    Gets or sets a value indicating whether to show the week numbers.

    Declaration
    public bool ShowWeekNumbers { get; set; }
    Property Value
    Type Description
    System.Boolean

    true if the week numbers can be displayed; otherwise, false. The default value is false.

    Remarks

    The week number can be formatted using WeekNumberFormat The UI can be customized using the CalendarItem.ItemTempalateSelectorproperty.

    See Also
    WeekNumberRule

    WeekNumberFormat

    Gets or sets a value that specifies the format of the week number.

    Declaration
    public string WeekNumberFormat { get; set; }
    Property Value
    Type Description
    System.String

    The default value is string.Empty.

    Remarks

    When the value is “W 0”, week numbers are shown as W 1, W 2, W 3, … When the value is “00”, week numbers are shown as 01, 02, 03, …, 10, 11, ….

    See Also
    https://docs.microsoft.com/en-us/dotnet/standard/base-types/custom-numeric-format-strings#character-literals

    WeekNumberRule

    Gets or sets a value that specifies the rule for the first week of the year.

    Declaration
    public CalendarWeekRule WeekNumberRule { get; set; }
    Property Value
    Type Description
    System.Globalization.CalendarWeekRule

    The default value is System.Globalization.CalendarWeekRule.FirstDay.

    Remarks

    When the WeekNumberRule value is System.Globalization.CalendarWeekRule.FirstDay, then the first week of the year starts on the first day of the year. When the WeekNumberRule value is System.Globalization.CalendarWeekRule.FirstFourDayWeek, then the first week should have at least four days. When the WeekNumberRule value is System.Globalization.CalendarWeekRule.FirstFullWeek, then the first week should have all the seven days.

    Methods

    AttachFlyout()

    Attaches the DropDownFlyout to SfCalendarDatePicker.

    Declaration
    protected override void AttachFlyout()
    Overrides
    DateTimePickerBase.AttachFlyout()

    Dispose(Boolean)

    Disposes all the resources used by the SfCalendarDatePicker class.

    Declaration
    protected override void Dispose(bool disposing)
    Parameters
    Type Name Description
    System.Boolean disposing

    Indicates whether the call is from Dispose method or from a System.GC.SuppressFinalize(System.Object).

    Overrides
    SfDropDownBase.Dispose(Boolean)

    OnAcceptButtonClicked()

    Called when Accept button is clicked.

    Declaration
    protected override void OnAcceptButtonClicked()
    Overrides
    SfDropDownBase.OnAcceptButtonClicked()

    OnApplyTemplate()

    Declaration
    protected override void OnApplyTemplate()
    Overrides
    DateTimePickerBase.OnApplyTemplate()

    OnCreateAutomationPeer()

    Declaration
    protected override AutomationPeer OnCreateAutomationPeer()
    Returns
    Type
    Microsoft.UI.Xaml.Automation.Peers.AutomationPeer

    UpdateValues()

    Updates the Syncfusion.UI.Xaml.Editors.DateTimeHandler properties value.

    Declaration
    protected override void UpdateValues()
    Overrides
    DateTimePickerBase.UpdateValues()

    Events

    CalendarItemPrepared

    Occurs when calendar item is preparing.

    Declaration
    public event EventHandler<CalendarItemPreparedEventArgs> CalendarItemPrepared
    Event Type
    Type
    System.EventHandler<CalendarItemPreparedEventArgs>
    Remarks

    Allows to change the text of specific dates using DisplayText.

    Examples
    public MainPage()
    {
        this.InitializeComponent();
        SfCalendarDatePicker calendarDatePicker = new SfCalendarDatePicker();
        calendarDatePicker.ItemPrepared += Blockout_ItemPrepared;
    }
    // Blackout all weekends when calender item is being prepared.
    private void Blockout_ItemPrepared(object sender, CalendarItemPreparedEventArgs e)
    {
        if (e.ItemInfo.ItemType == CalendarItemType.Day &&
            (e.ItemInfo.Date.DayOfWeek == DayOfWeek.Saturday ||
            e.ItemInfo.Date.DayOfWeek == DayOfWeek.Sunday))
        {
            e.ItemInfo.IsBlackout = true;
        }
    }

    SelectedDateChanged

    Occurs when the SelectedDate value is changed.

    Declaration
    public event EventHandler<SelectedDateChangedEventArgs> SelectedDateChanged
    Event Type
    Type
    System.EventHandler<SelectedDateChangedEventArgs>

    SelectedDateChanging

    Occurs before when the SelectedDate value is changed.

    Declaration
    public event EventHandler<DateChangingEventArgs> SelectedDateChanging
    Event Type
    Type
    System.EventHandler<DateChangingEventArgs>
    Remarks

    Allows to prevent setting the today date as selected date when today's date is in BlackoutDates collection.

    Examples
    public MainPage()
    {
    this.InitializeComponent();
    SfCalendarDatePicker calendarDatePicker = new SfCalendarDatePicker();
    calendarDatePicker.DateChanging += calendarDatePicker_DateChanging;
    }
    // cancels the selected date changing process.
    private void calendarDatePicker_DateChanging(object sender, DateChangingEventArgs e)
    {
     if(calendarDatePicker.BlackoutDates.Contains((DateTimeOffset) e.NewDate))
     {
      e.Cancel = true;
     }
    }

    Implements

    System.IDisposable
    Back to top Generated by DocFX
    Copyright © 2001 - 2025 Syncfusion Inc. All Rights Reserved