syncfusion-winui-calendar

WinUI Calendar (SfCalendar)

Comprehensive guide for implementing the Syncfusion WinUI Calendar (SfCalendar) control for date selection in Windows desktop applications. The Calendar control supports single, multiple, and range date selection with extensive customization options, navigation between different views, date restrictions, and localization.

When to Use This Skill

Use this skill when you need to:

• Create calendar controls for date selection in WinUI desktop applications
• Select dates in single, multiple, or range modes
• Navigate views between month, year, decade, and century
• Restrict dates using min/max dates and blackout dates
• Customize UI with templates, special date highlighting, and styling
• Localize calendars for different cultures and languages
• Display week numbers with various calculation rules
• Handle date selection events for validation or business logic
• Implement accessible date pickers with keyboard navigation
• Troubleshoot calendar rendering or data binding issues

Component Overview

SfCalendar is the primary date selection control for WinUI desktop applications, offering:

• Selection Modes: Single, Multiple, Range, or None
• View Navigation: Month, Year, Decade, and Century views
• Date Restrictions: MinDate, MaxDate, and BlackoutDates collections
• Customization: Cell templates, special date highlighting, and theme integration
• Localization: Support for multiple calendar types and cultures
• Week Numbers: Configurable week numbering with ISO 8601 support
• Keyboard Support: Full keyboard navigation and accessibility
• Data Binding: MVVM-friendly with SelectedDate and SelectedDates binding

Control Structure:

• Month view with day cells (default)
• Year view with month cells
• Decade view with year cells
• Century view with decade cells
• Header for navigation and current view title
• Navigation buttons for scrolling

Documentation and Navigation Guide

Getting Started

📄 Read: references/getting-started.md

• Creating a WinUI 3 desktop application
• Installing Syncfusion.Calendar.WinUI NuGet package
• Adding Calendar control in XAML
• Adding Calendar control in C#
• Basic date selection
• Control structure overview

Selection Features

📄 Read: references/selection.md

• Selection modes: None, Single, Multiple, Range
• SelectedDate property (single selection)
• SelectedDates collection (multiple/range selection)
• Programmatic date selection
• Selection changed events
• Data binding selected dates

Navigation and Display

📄 Read: references/navigation.md

• Display modes: Month, Year, Decade, Century
• Navigating between views
• SetDisplayDate method to bring dates into view
• Min/Max display mode restrictions
• Selection based on view restrictions
• Navigation direction (vertical/horizontal scrolling)

Date Restrictions

📄 Read: references/date-restrictions.md

• MinDate and MaxDate properties
• Restricting selectable date ranges
• BlackoutDates collection
• Blocking specific dates from selection
• Validating date selection
• Styling disabled dates

Localization and Formatting

📄 Read: references/localization-formatting.md

• Culture and language support
• FormatString for custom date formats
• Abbreviated day and month names
• RTL (Right-to-Left) support
• FlowDirection property
• Date formatting patterns

UI Customization

📄 Read: references/customization.md

• Cell templates (DataTemplate)
• Special date highlighting with icons
• Custom cell styling
• Header customization
• Background and foreground colors
• Border and appearance customization
• Theme integration

Week Numbers

📄 Read: references/week-numbers.md

• ShowWeekNumbers property
• WeekNumberRule options
• Week number formatting
• FirstDay, FirstFourDayWeek, FirstFullWeek rules
• Culture-specific week calculations

Quick Start Example

Here's a minimal working example to get started:

1. Add Namespace

XAML:

<Window xmlns:calendar="using:Syncfusion.UI.Xaml.Calendar">

C#:

using Syncfusion.UI.Xaml.Calendar;

2. Create Basic Calendar (XAML)

<Window
    x:Class="CalendarApp.MainWindow"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:calendar="using:Syncfusion.UI.Xaml.Calendar">
    
    <Grid>
        <calendar:SfCalendar x:Name="sfCalendar" />
    </Grid>
</Window>

3. Or Create Programmatically (C#)

using Syncfusion.UI.Xaml.Calendar;

namespace CalendarApp
{
    public sealed partial class MainWindow : Window
    {
        public MainWindow()
        {
            this.InitializeComponent();
            
            // Create calendar programmatically
            SfCalendar sfCalendar = new SfCalendar();
            this.Content = sfCalendar;
        }
    }
}

4. Select a Date (Optional)

// Select today's date
sfCalendar.SelectedDate = DateTimeOffset.Now;

// Or select a specific date
sfCalendar.SelectedDate = new DateTimeOffset(new DateTime(2026, 3, 22));

Common Patterns

Pattern 1: Single Date Selection

<calendar:SfCalendar 
    x:Name="calendar"
    SelectionMode="Single"
    SelectedDate="{x:Bind ViewModel.SelectedDate, Mode=TwoWay}" />

// Access selected date
DateTimeOffset? selected = calendar.SelectedDate;

Pattern 2: Multiple Date Selection

<calendar:SfCalendar 
    x:Name="calendar"
    SelectionMode="Multiple"
    SelectedDates="{x:Bind ViewModel.SelectedDates, Mode=TwoWay}" />

// Access multiple selected dates
DateTimeOffsetCollection selectedDates = calendar.SelectedDates;

Pattern 3: Date Range Selection

<calendar:SfCalendar 
    x:Name="calendar"
    SelectionMode="Range" />

Pattern 4: Restrict Date Range

<calendar:SfCalendar 
    x:Name="calendar"
    MinDate="2026-01-01"
    MaxDate="2026-12-31" />

// Set date restrictions in code
calendar.MinDate = new DateTimeOffset(new DateTime(2026, 1, 1));
calendar.MaxDate = new DateTimeOffset(new DateTime(2026, 12, 31));

Pattern 5: Block Specific Dates

// Create blackout dates collection
DateTimeOffsetCollection blackoutDates = new DateTimeOffsetCollection();
blackoutDates.Add(new DateTimeOffset(new DateTime(2026, 3, 25))); // Holiday
blackoutDates.Add(new DateTimeOffset(new DateTime(2026, 12, 25))); // Christmas

calendar.BlackoutDates = blackoutDates;

Pattern 6: Navigate to Specific Month

// Navigate to a specific date's month
calendar.SetDisplayDate(new DateTimeOffset(new DateTime(2026, 6, 15)));

Pattern 7: Restrict Navigation to Year View

<calendar:SfCalendar 
    x:Name="calendar"
    MinDisplayMode="Month"
    MaxDisplayMode="Year" />

Pattern 8: ViewModel Data Binding

public class CalendarViewModel : INotifyPropertyChanged
{
    private DateTimeOffset? selectedDate;
    
    public DateTimeOffset? SelectedDate
    {
        get => selectedDate;
        set
        {
            selectedDate = value;
            OnPropertyChanged(nameof(SelectedDate));
        }
    }
    
    public event PropertyChangedEventHandler PropertyChanged;
    
    protected void OnPropertyChanged(string propertyName)
    {
        PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(propertyName));
    }
}

<calendar:SfCalendar 
    SelectedDate="{x:Bind ViewModel.SelectedDate, Mode=TwoWay}" />

Key Properties Reference

Selection Properties

Property	Type	Description
SelectedDate	DateTimeOffset?	Gets or sets the selected date (single selection mode)
SelectedDates	DateTimeOffsetCollection	Gets or sets the collection of selected dates (multiple/range modes)
SelectedRange	DateTimeOffsetRange	Gets the selected date range when SelectionMode is Range
SelectionMode	CalendarSelectionMode	Date selection mode: None, Single, Multiple, Range
SelectionHighlightMode	SelectionHighlightMode	Highlight style for selected dates: Outline, Filled
SelectionShape	SelectionShape	Shape of selection indicator: Circle, Rectangle

Date Restriction Properties

Property	Type	Description
MinDate	DateTimeOffset	Minimum selectable date (default: 1/1/1920)
MaxDate	DateTimeOffset	Maximum selectable date (default: 12/31/2120)
BlackoutDates	DateTimeOffsetCollection	Collection of non-selectable (blocked) dates

Display and Navigation Properties

Property	Type	Description
DisplayMode	CalendarDisplayMode	Current view: Month, Year, Decade, Century
MinDisplayMode	CalendarDisplayMode	Minimum view level users can navigate to
MaxDisplayMode	CalendarDisplayMode	Maximum view level users can navigate to
NavigationDirection	CalendarNavigationDirection	Scroll direction within view: Vertical, Horizontal
OutOfScopeVisibility	OutOfScopeVisibility	Show/hide dates from adjacent months: Enabled, Hidden
HeaderInfo	object	Custom header content for the calendar

Localization and Formatting Properties

Property	Type	Description
CalendarIdentifier	string	Calendar system type: GregorianCalendar, HijriCalendar, HebrewCalendar, etc.
FirstDayOfWeek	FirstDayOfWeek	First day of week: Sunday, Monday, Tuesday, etc.
DayFormat	string	Format pattern for day numbers (e.g., "{day.integer(2)}")
MonthFormat	string	Format pattern for month names (e.g., "{month.full}")
DayOfWeekFormat	string	Format pattern for day-of-week headers (e.g., "{dayofweek.abbreviated(3)}")
MonthHeaderFormat	string	Format pattern for month/year header (e.g., "{month.full} {year.full}")
NumberOfWeeksInView	int	Number of week rows displayed in month view (default: 6)

Week Number Properties

Property	Type	Description
ShowWeekNumbers	bool	Display week numbers column (default: false)
WeekNumberRule	CalendarWeekRule	Week calculation rule: FirstDay, FirstFourDayWeek, FirstFullWeek
WeekNumberFormat	string	Format for week numbers (use # as placeholder, e.g., "W #")

Common Use Cases

Event Scheduling Application

Create event scheduling interfaces where users select single dates for appointments, meetings, or reminders with future date restrictions and business day filtering.

Vacation Request System

Build vacation management systems with multiple date selection, blackout dates for company holidays, and range selection for consecutive vacation days.

Appointment Booking Calendar

Implement booking systems with dynamic date availability, blackout dates for unavailable slots, and real-time availability checking through ItemPrepared event.

International Date Picker

Develop multi-language applications with localized calendars supporting different calendar types (Hijri, Hebrew, Persian), RTL languages, and culture-specific formatting.

Date Range Filtering

Create data filtering interfaces where users select date ranges for reports, analytics dashboards, or transaction queries with min/max date boundaries.

Credit Card Expiry Selector

Implement month/year-only selectors for credit card expiration dates by restricting navigation to Year and Decade views only.

---

Next Steps: Read the reference documentation above based on what you need to implement. Start with getting-started.md for initial setup, then explore specific features as needed.