syncfusion-blazor-calendars

# Implementing Syncfusion Blazor Calendars ## Calendar The Calendar component is a lightweight, feature-rich date selection component that provides flexible date picking, multiple views (month/year/decade), date range constraints, localization, and accessibility compliance. Use this skill whenever you need to implement date selection, calendar display, or date-based UI interactions. ### When to Use This Skill **Use this skill when:** - Building date pickers, calendar widgets, or date selection interfaces - Adding date range constraints (Min/Max dates) - Implementing multi-month or drill-down date selection (Year/Decade views) - Handling date value changes and events - Styling calendars or customizing appearance - Supporting international date formats and RTL layouts - Creating accessible calendar interfaces with keyboard navigation **Related components:** - **DatePicker** (date input with calendar dropdown) - **DateRangePicker** (date range selection) - **DateTimePicker** (date + time selection) - **Scheduler** (complex date-based scheduling) ### Component Overview | Feature | Details | |---------|---------| | **Views** | Month (default), Year, Decade - hierarchical drill-down navigation | | **Selection** | Single date, date ranges (Min/Max), multi-select | | **Data Types** | `DateTime`, `DateTime?`, `DateOnly` (.NET 6+) | | **Binding** | One-way, two-way (`@bind-Value`), dynamic | | **Events** | `ValueChange`, `OnRenderDayCell`, `Created`, `Destroyed`, `Navigated` | | **Localization** | Multi-language, RTL support, locale customization | | **Accessibility** | WCAG 2.2 AA, keyboard navigation, screen reader support | | **Styling** | CSS customization, theme integration, special date highlights | ### Documentation & Navigation Guide #### Getting Started 📄 **Read:** [references/getting-started.md](references/calendar-getting-started.md) - Installation & NuGet packages - Web & Server app setup - Blazor namespaces & service registration - Basic calendar implementation - Min/Max date constraints #### Calendar Views & Navigation 📄 **Read:** [references/calendar-views.md](references/calendar-calendar-views.md) - Month, Year, Decade views - Start & Depth properties - View restrictions & drill-down navigation - Restricting date selection depth #### Date Selection & Data Binding 📄 **Read:** [references/date-selection-binding.md](references/calendar-date-selection-binding.md) - Value property & date binding - One-way vs two-way binding (`@bind-Value`) - DateOnly support (.NET 6+) - Dynamic value changes - Date range constraints #### Events & Interactions 📄 **Read:** [references/events-handling.md](references/calendar-events-handling.md) - ValueChange event (date selection) - Selected/DeSelected events (multi-selection) - OnRenderDayCell event (custom rendering) - Created & Destroyed lifecycle events - Navigated event (view changes) - Event args & reactive patterns - Using CalendarEvents child component #### Styling & Customization 📄 **Read:** [references/styling-appearance.md](references/calendar-styling-appearance.md) - CSS customization patterns - Background colors, borders, hover states - Day cell styling - Header & title customization - Today button & selected date styling - Special date highlighting #### Localization & Globalization 📄 **Read:** [references/localization-globalization.md](references//calendar-localization-globalization.md) - Locale support & language files - Right-to-Left (RTL) layouts - Islamic calendar & custom calendars - Week customization (first day of week) - Date format localization #### Accessibility & Keyboard Navigation 📄 **Read:** [references/accessibility.md](references/calendar-accessibility.md) - WCAG 2.2 AA compliance - Screen reader support (WAI-ARIA) - Keyboard navigation shortcuts - Focus management & ARIA attributes #### Advanced Features & Patterns 📄 **Read:** [references/advanced-features.md](references/calendar-advanced-features.md) - Show/hide other month dates - Custom cell rendering patterns - Multiple date selection - Week number display - Performance optimization - Common integration patterns ### Quick Start Example ```razor @using Syncfusion.Blazor.Calendars <!-- Basic Calendar --> <SfCalendar TValue="DateTime?" Value="@SelectedDate"></SfCalendar> <!-- Calendar with Date Range --> <SfCalendar TValue="DateTime?" Value="@SelectedDate" Min="@MinDate" Max="@MaxDate"> </SfCalendar> <!-- Calendar with Value Change Event --> <SfCalendar TValue="DateTime?" @bind-Value="@SelectedDate"> <CalendarEvents TValue="DateTime?" ValueChange="@OnDateChanged"></CalendarEvents> </SfCalendar> <!-- Multi-Selection Calendar --> <SfCalendar TValue="DateTime?" IsMultiSelection="true" @bind-Values="@SelectedDates"> <CalendarEvents TValue="DateTime?" Selected="@OnDateSelected" DeSelected="@OnDateDeselected"> </CalendarEvents> </SfCalendar> @code { public DateTime? SelectedDate { get; set; } = DateTime.Now; public DateTime[] SelectedDates { get; set; } = new DateTime[] { }; private void OnDateChanged(ChangedEventArgs<DateTime?> args) { SelectedDate = args.Value; // Handle date change } private void OnDateSelected(SelectedEventArgs<DateTime?> args) { // Handle date added to selection } private void OnDateDeselected(DeSelectedEventArgs<DateTime?> args) { // Handle date removed from selection } } ``` ### Common Patterns #### Pattern 1: Date Range Selection Define Min and Max boundaries to constrain user selection: ```razor <SfCalendar TValue="DateTime?" Value="@SelectedDate" Min="@MinDate" Max="@MaxDate"></SfCalendar> ``` #### Pattern 2: Two-Way Data Binding Keep Calendar in sync with component state: ```razor <p>Selected: @SelectedDate</p> <SfCalendar TValue="DateTime?" @bind-Value="@SelectedDate"></SfCalendar> ``` #### Pattern 3: Custom Cell Rendering Highlight or customize specific date cells during render: ```razor <SfCalendar TValue="DateTime?"> <CalendarEvents TValue="DateTime?" OnRenderDayCell="@CustomizeCell"></CalendarEvents> </SfCalendar> ``` #### Pattern 4: View Restrictions Limit navigation to specific view levels (e.g., Year → Month only): ```razor <SfCalendar TValue="DateTime?" Start="CalendarView.Year" Depth="CalendarView.Month"></SfCalendar> ``` #### Pattern 5: Localization Render calendar in specific language/culture: ```razor <SfCalendar TValue="DateTime?" EnableRtl="false"></SfCalendar> ``` ### Key Props & When to Use | Property | Type | Purpose | Example | |----------|------|---------|---------| | `Value` | `TValue` | Selected date (one-way binding) | `Value="@SelectedDate"` | | `@bind-Value` | `TValue` | Two-way data binding | `@bind-Value="@SelectedDate"` | | `Values` | `DateTime[]` | Multiple selected dates (multi-select mode) | `Values="@SelectedDates"` | | `@bind-Values` | `DateTime[]` | Two-way binding for multi-selection | `@bind-Values="@SelectedDates"` | | `IsMultiSelection` | `bool` | Enable multiple date selection | `IsMultiSelection="true"` | | `Min` | `DateTime` | Earliest selectable date (inclusive) | `Min="@minSelectableDate"` | | `Max` | `DateTime` | Latest selectable date (inclusive) | `Max="@maxSelectableDate"` | | `Start` | `CalendarView` | Initial view (Month/Year/Decade) | `Start="CalendarView.Year"` | | `Depth` | `CalendarView` | Deepest view level for drilling | `Depth="CalendarView.Month"` | | `ShowTodayButton` | `bool` | Display "Today" button in footer | `ShowTodayButton="true"` | | `CalendarMode` | `CalendarType` | Calendar system (Gregorian/Islamic) | `CalendarMode="CalendarType.Islamic"` | | `WeekRule` | `CalendarWeekRule` | Week numbering calculation rule | `WeekRule="CalendarWeekRule.FirstDay"` | | `DayHeaderFormat` | `DayHeaderFormats` | Day header display format | `DayHeaderFormat="DayHeaderFormats.Short"` | | `EnableRtl` | `bool` | Right-to-left layout | `EnableRtl="true"` | | `WeekNumber` | `bool` | Display week numbers in calendar | `WeekNumber="true"` | | `FirstDayOfWeek` | `int` | First day (0=Sunday, 1=Monday) | `FirstDayOfWeek="1"` | | `CssClass` | `string` | Custom CSS class for styling | `CssClass="custom-calendar"` | | `Enabled` | `bool` | Enable/disable component | `Enabled="false"` | ### Common Use Cases 1. **Appointment Booking**: Calendar with date range (available days) + event handling 2. **Date Filter**: Multi-view calendar for drilling down to specific date 3. **Deadline Selection**: Min/Max constraints to valid date ranges 4. **Report Viewing**: Year/Month view for period selection 5. **International App**: RTL + locale support for multi-language UIs 6. **Accessible Forms**: Keyboard-navigable date input with screen reader support ### Working with Events All calendar components use **child event components** to declare event handlers. This approach provides type safety and clear separation of concerns. #### Event Child Components - **Calendar**: Use `<CalendarEvents>` child component - **DatePicker**: Use `<DatePickerEvents>` child component - **DateRangePicker**: Use `<DateRangePickerEvents>` child component - **DateTimePicker**: Use `<DateTimePickerEvents>` child component - **TimePicker**: Use `<TimePickerEvents>` child component #### Example: Calendar with Events ```razor <SfCalendar TValue="DateTime?" @bind-Value="@SelectedDate"> <CalendarEvents TValue="DateTime?" ValueChange="@OnValueChanged" OnRenderDayCell="@OnDayCellRender" Navigated="@OnNavigated"> </CalendarEvents> </SfCalendar> @code { private DateTime? SelectedDate { get; set; } private void OnValueChanged(ChangedEventArgs<DateTime?> args) { Console.WriteLine($"Date changed: {args.Value}"); } private void OnDayCellRender(RenderDayCellEventArgs args) { // Disable weekends if (args.Date.DayOfWeek == DayOfWeek.Saturday || args.Date.DayOfWeek == DayOfWeek.Sunday) { args.IsDisabled = true; } } private void OnNavigated(NavigatedEventArgs args) { Console.WriteLine($"Navigated to: {args.View}"); } } ``` #### Common Event Patterns **Pattern 1: Value Change with Validation** ```razor <SfDatePicker TValue="DateTime?" @bind-Value="@OrderDate"> <DatePickerEvents TValue="DateTime?" ValueChange="@ValidateAndUpdate"></DatePickerEvents> </SfDatePicker> @code { private DateTime? OrderDate { get; set; } private void ValidateAndUpdate(ChangedEventArgs<DateTime?> args) { if (args.Value.HasValue && args.Value.Value > DateTime.Now.AddMonths(6)) { // Show error - date too far in future OrderDate = DateTime.Now; } else { OrderDate = args.Value; } } } ``` **Pattern 2: Popup Lifecycle Management** ```razor <SfDateTimePicker TValue="DateTime?" @bind-Value="@AppointmentTime"> <DateTimePickerEvents TValue="DateTime?" OnOpen="@HandlePopupOpen" OnClose="@HandlePopupClose"> </DateTimePickerEvents> </SfDateTimePicker> @code { private DateTime? AppointmentTime { get; set; } private void HandlePopupOpen(PopupObjectArgs args) { Console.WriteLine("Popup opened"); // Can cancel opening: args.Cancel = true; } private void HandlePopupClose(PopupObjectArgs args) { Console.WriteLine("Popup closed"); } } ``` **Pattern 3: Custom Cell Rendering** ```razor <SfCalendar TValue="DateTime?" @bind-Value="@EventDate"> <CalendarEvents TValue="DateTime?" OnRenderDayCell="@CustomizeCells"></CalendarEvents> </SfCalendar> @code { private DateTime? EventDate { get; set; } private List<DateTime> EventDates = new List<DateTime> { DateTime.Now.AddDays(5), DateTime.Now.AddDays(10) }; private void CustomizeCells(RenderDayCellEventArgs args) { // Highlight event dates if (EventDates.Any(d => d.Date == args.Date.Date)) {