Class SfCalendar<TValue>
Represents the Syncfusion Blazor Calendar component, which provides a user-friendly interface for displaying and selecting dates on a Gregorian calendar.
Implements
Inherited Members
Namespace: Syncfusion.Blazor.Toolkit.Calendars
Assembly: Syncfusion.Blazor.Toolkit.dll
Syntax
public class SfCalendar<TValue> : CalendarBase<TValue>, IAsyncDisposableType Parameters
| Name |
|---|
| TValue |
Remarks
The SfCalendar<TValue> component allows users to navigate through months and years, select single or multiple dates, and customize the display with templates and styles. It supports localization, RTL, and various accessibility features. For advanced scenarios, the component raises events to handle value changes, cell rendering, and navigation actions.
This component is commonly used for inputting or displaying dates inline, either standalone or as part of a larger form.
Examples
The following example demonstrates how to declare and use the SfCalendar<TValue> component in a Razor file:
<SfCalendar TValue="DateTime" @bind-Value="SelectedDate"></SfCalendar>
@code {
private DateTime? SelectedDate = DateTime.Today;
}Example of using SfCalendar component with multi-date selection enabled:
<SfCalendar TValue="DateTime" IsMultiSelection="true" @bind-Values="SelectedDates"></SfCalendar>Here is an example of rendering an SfCalendar in a Blazor component:
<SfCalendar TValue="DateTime" />Constructors
SfCalendar()
Declaration
public SfCalendar()Properties
Created
Gets or sets an event callback that is invoked when the calendar component is created and initialized.
Declaration
public EventCallback<object> Created { get; set; }Property Value
| Type | Description |
|---|---|
| Microsoft.AspNetCore.Components.EventCallback<System.Object> | An Microsoft.AspNetCore.Components.EventCallback<> of type |
Remarks
This event is useful for executing code after the calendar's resources have been fully allocated and rendered.
Examples
<SfCalendar TValue="DateTime?" Created="@OnCreated">
</SfCalendar>
@code {
private void OnCreated(object args) {
Console.WriteLine("Calendar created.");
}
}DayCellRendering
Gets or sets an event callback that is invoked as each calendar day cell is rendered.
Declaration
public EventCallback<RenderDayCellEventArgs> DayCellRendering { get; set; }Property Value
| Type | Description |
|---|---|
| Microsoft.AspNetCore.Components.EventCallback<RenderDayCellEventArgs> | An Microsoft.AspNetCore.Components.EventCallback<> that is triggered when a day cell is rendered in the calendar. The callback receives a RenderDayCellEventArgs providing details for customizing the cell appearance. |
Remarks
This event allows customizing the visual appearance or properties of individual day cells as they are rendered in the calendar UI.
Examples
<SfCalendar TValue="DateTime?" DayCellRendering="@CellRendered">
</SfCalendar>
@code {
private void CellRendered(RenderDayCellEventArgs args) {
args.CellData.ClassList = "e-custom-style";
}
}DeSelected
Gets or sets an event callback that is invoked after deselecting a value in the calendar.
Declaration
public EventCallback<DeSelectedEventArgs<TValue>> DeSelected { get; set; }Property Value
| Type | Description |
|---|---|
| Microsoft.AspNetCore.Components.EventCallback<DeSelectedEventArgs<TValue>> | An Microsoft.AspNetCore.Components.EventCallback<> that is invoked when a value is deselected. The callback receives a DeSelectedEventArgs<T> instance providing details of the deselected date. |
Remarks
This event is only triggered when the IsMultiSelection property is enabled, allowing multiple date selection and deselection in the calendar.
Examples
<SfCalendar TValue="DateTime?" IsMultiSelection="true" DeSelected="@ValueDeselected">
</SfCalendar>
@code {
private void ValueDeselected(DeSelectedEventArgs<DateTime?> args) {
Console.WriteLine($"Deselected value: {args.Value}");
}
}Destroyed
Gets or sets an event callback that is invoked when the calendar component is disposed and destroyed.
Declaration
public EventCallback<object> Destroyed { get; set; }Property Value
| Type | Description |
|---|---|
| Microsoft.AspNetCore.Components.EventCallback<System.Object> | An Microsoft.AspNetCore.Components.EventCallback<> of type |
Remarks
Use this event to perform cleanup or release resources associated with the calendar when it is destroyed.
Examples
<SfCalendar TValue="DateTime?" Destroyed="@OnDestroyed">
</SfCalendar>
@code {
private void OnDestroyed(object args) {
Console.WriteLine("Calendar destroyed.");
}
}HtmlAttributes
Gets or sets a collection of additional HTML attributes such as styles, CSS classes, and other custom settings to be applied to the calendar's root element.
Declaration
public Dictionary<string, object> HtmlAttributes { get; set; }Property Value
| Type | Description |
|---|---|
| System.Collections.Generic.Dictionary<System.String, System.Object> | A System.Collections.Generic.Dictionary<, > of |
Remarks
Use this property to attach custom styles, attributes, or data-* attributes to the calendar component for advanced customization and integration scenarios.
Examples
Add custom classes and styles to the calendar:
<SfCalendar TValue="DateTime" HtmlAttributes="@new Dictionary<string, object>{{ "class", "custom-calendar" }, { "data-type", "events" }}"></SfCalendar>IsMultiSelection
Gets or sets a value that indicates whether the calendar allows selection of multiple dates concurrently.
Declaration
public bool IsMultiSelection { get; set; }Property Value
| Type | Description |
|---|---|
| System.Boolean |
|
Remarks
When set to true, the user can select multiple non-contiguous dates within the calendar. When false, single date selection mode applies.
Examples
Enable multiple date selection on the calendar:
<SfCalendar TValue="DateTime" IsMultiSelection="true" @bind-Values="SelectedDates"></SfCalendar>Navigated
Gets or sets an event callback that is invoked after the calendar is navigated to another level or within the same level of the calendar view.
Declaration
public EventCallback<NavigatedEventArgs> Navigated { get; set; }Property Value
| Type | Description |
|---|---|
| Microsoft.AspNetCore.Components.EventCallback<NavigatedEventArgs> | An Microsoft.AspNetCore.Components.EventCallback<> that is triggered after navigation in the calendar. The callback receives a NavigatedEventArgs instance describing the navigation context. |
Remarks
Use this event to track and respond to changes in the calendar's current view, such as when switching between months, years, or decades.
Examples
<SfCalendar TValue="DateTime?" Navigated="@ViewNavigated">
</SfCalendar>
@code {
private void ViewNavigated(NavigatedEventArgs args) {
Console.WriteLine($"Current view: {args.View}");
}
}Selected
Gets or sets an event callback that is invoked after one or more date values are selected in the calendar.
Declaration
public EventCallback<SelectedEventArgs<TValue>> Selected { get; set; }Property Value
| Type | Description |
|---|---|
| Microsoft.AspNetCore.Components.EventCallback<SelectedEventArgs<TValue>> | An Microsoft.AspNetCore.Components.EventCallback<> that is invoked when dates are selected. The callback receives a SelectedEventArgs<T> instance containing the information about the selected value(s). |
Remarks
This event is raised after a date or multiple dates are selected by the user via the calendar UI or through code.
Examples
<SfCalendar TValue="DateTime?" Selected="@ValueSelected">
</SfCalendar>
@code {
private void ValueSelected(SelectedEventArgs<DateTime?> args) {
Console.WriteLine($"Selected value: {args.Value}");
}
}TabIndex
Gets or sets the tab index which determines the tab order for the component in the page.
Declaration
public int TabIndex { get; set; }Property Value
| Type | Description |
|---|---|
| System.Int32 | An |
Remarks
This value controls the order in which focus shifts when the user presses the Tab key.
Examples
Set a custom tab index for accessibility:
<SfCalendar TValue="DateTime" TabIndex="2"></SfCalendar>ValueChange
Gets or sets an event callback that is invoked when the Values property changes.
Declaration
public EventCallback<ChangedEventArgs<TValue>> ValueChange { get; set; }Property Value
| Type | Description |
|---|---|
| Microsoft.AspNetCore.Components.EventCallback<ChangedEventArgs<TValue>> | An Microsoft.AspNetCore.Components.EventCallback<> that is triggered when the calendar values are changed. The callback receives an instance of ChangedEventArgs<T> containing the new value and other details. |
Remarks
Use this event to respond to changes in the selected dates when interacting with the calendar, such as via UI input or programmatic assignment.
Examples
<SfCalendar TValue="DateTime?" ValueChange="@ValueChange">
</SfCalendar>
@code {
private void ValueChange(ChangedEventArgs<DateTime?> args) {
Console.WriteLine($"Changed value: {args.Value}");
}
}Values
Gets or sets an array of System.DateTime values representing the selected dates in the calendar.
Declaration
public DateTime[] Values { get; set; }Property Value
| Type | Description |
|---|---|
| System.DateTime[] | An array of System.DateTime objects that indicate the currently selected dates. |
Remarks
This can be used for binding multiple selected dates in multi-selection mode. Binding this property will update the calendar with the selected values.
Examples
Bind selected date values from a model:
<SfCalendar TValue="DateTime" @bind-Values="MySelectedDates"></SfCalendar>ValuesChanged
Gets or sets the event callback that is triggered when the Values property changes.
Declaration
public EventCallback<DateTime[]> ValuesChanged { get; set; }Property Value
| Type | Description |
|---|---|
| Microsoft.AspNetCore.Components.EventCallback<System.DateTime[]> | An Microsoft.AspNetCore.Components.EventCallback<> of type |
Remarks
This event can be used to perform additional actions or synchronize state when the collection of selected dates changes.
Examples
Subscribe to value change events in code:
<SfCalendar TValue="DateTime" @bind-Values="SelectedDates" ValuesChanged="OnValuesChanged"></SfCalendar>
@code {
private void OnValuesChanged(DateTime[] newValues) {
// Handle the changed dates
}
}ValuesExpression
Gets or sets the System.Linq.Expressions.Expression used to bind multiple values to the calendar in two-way binding scenarios.
Declaration
public Expression<Func<DateTime[]>> ValuesExpression { get; set; }Property Value
| Type | Description |
|---|---|
| System.Linq.Expressions.Expression<System.Func<System.DateTime[]>> | An expression of lambda type |
Remarks
Typically used internally for validation and model binding when implementing complex forms with multiple selected dates.
Examples
Example usage inside a form for complex model binding:
<EditForm Model="MyModel">
<SfCalendar TValue="DateTime"
ValuesExpression="@(() => MyModel.SelectedDates)"
@bind-Values="MyModel.SelectedDates">
</SfCalendar>
</EditForm>Methods
AddDatesAsync(DateTime[])
Adds one or more dates to the Values selection when the calendar is in multi-selection mode.
Declaration
public Task AddDatesAsync(DateTime[] dates = null)Parameters
| Type | Name | Description |
|---|---|---|
| System.DateTime[] | dates | An array of System.DateTime objects to be added to the calendar's selection. If |
Returns
| Type | Description |
|---|---|
| System.Threading.Tasks.Task | A task representing the asynchronous add operation. |
Remarks
This method updates the selected dates only when IsMultiSelection is set to true.
It does not allow duplicates in the selection. If a date is already selected, it will not be added again.
Examples
await calendar.AddDatesAsync(new DateTime[] { new DateTime(2022,2,12), new DateTime(2022,2,14) });BuildRenderTree(RenderTreeBuilder)
Declaration
protected override void BuildRenderTree(RenderTreeBuilder __builder)Parameters
| Type | Name | Description |
|---|---|---|
| Microsoft.AspNetCore.Components.Rendering.RenderTreeBuilder | __builder |
CurrentView()
Returns the current view in which the calendar is displayed (such as Month, Year, or Decade).
Declaration
public string CurrentView()Returns
| Type | Description |
|---|---|
| System.String | A |
Remarks
Use this method to check which logical view is currently shown to the user. Typical use is in UI customization or conditionally showing controls based on calendar state.
Examples
var view = calendar.CurrentView();GetPersistDataAsync()
Retrieves the data to be persisted for this calendar instance upon browser refresh or reload.
Declaration
public Task<string> GetPersistDataAsync()Returns
| Type | Description |
|---|---|
| System.Threading.Tasks.Task<System.String> | A task representing the asynchronous operation. The task result contains a |
Remarks
Use this method to fetch stateful data such as selected values from browser storage for the current SfCalendar<TValue> instance using its unique identifier.
Examples
var persistData = await calendar.GetPersistDataAsync();NavigateAsync(CalendarView, TValue)
Navigates the calendar programmatically to a specified logical view and date.
Declaration
public Task NavigateAsync(CalendarView view, TValue date)Parameters
| Type | Name | Description |
|---|---|---|
| CalendarView | view | Specifies the target logical view of the calendar. Use CalendarView enum values: |
| TValue | date | The date to focus in the new view, of type |
Returns
| Type | Description |
|---|---|
| System.Threading.Tasks.Task | A System.Threading.Tasks.Task representing the asynchronous navigation operation. |
Remarks
Use this method for scenarios that require calendar navigation at runtime, automating view changes for guided workflows or conditional behaviors based on user actions or events.
Examples
await calendar.NavigateAsync(CalendarView.Year, DateTime.Now);RemoveDatesAsync(DateTime[])
Removes one or more dates from the Values selection when the calendar is in multi-selection mode.
Declaration
public Task RemoveDatesAsync(DateTime[] dates = null)Parameters
| Type | Name | Description |
|---|---|---|
| System.DateTime[] | dates | An array of System.DateTime objects specifying which dates to remove from the current selection.
If |
Returns
| Type | Description |
|---|---|
| System.Threading.Tasks.Task | A System.Threading.Tasks.Task representing the asynchronous remove operation. |
Remarks
This method updates the selected dates only if IsMultiSelection is true and selected Values are not empty.
Examples
await calendar.RemoveDatesAsync(new DateTime[] { new DateTime(2022,2,12) });