Class SfCalendar<TValue>
Represents a graphical Calendar UI component that displays a Gregorian calendar and allows users to select one or more dates with ease and accessibility.
Inherited Members
Namespace: Syncfusion.Blazor.Calendars
Assembly: Syncfusion.Blazor.dll
Syntax
public class SfCalendar<TValue> : CalendarBase<TValue>Type Parameters
| Name |
|---|
| TValue |
Remarks
The SfCalendar<TValue> provides date picking functionality suitable for forms, standalone popups, or embedded calendar scenarios and can be customized for appearance and behavior.
Examples
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" />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;
}Constructors
SfCalendar()
Declaration
public SfCalendar()Properties
ChildContent
Specifies the custom content to be rendered inside the body of the calendar component.
Declaration
public RenderFragment ChildContent { get; set; }Property Value
| Type | Description |
|---|---|
| Microsoft.AspNetCore.Components.RenderFragment | Accepts a Microsoft.AspNetCore.Components.RenderFragment that encapsulates child content for rendering within the UI element. |
Remarks
Use this property to insert additional markup or components within the calendar body for advanced scenarios. This API is reserved for internal or advanced customization cases only.
Examples
Add custom content to the calendar:
<SfCalendar TValue="DateTime">
<ChildContent>
<div>Calendar Footer Notes</div>
</ChildContent>
</SfCalendar>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>RootClass
Declaration
protected override string RootClass { get; set; }Property Value
| Type |
|---|
| System.String |
Overrides
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>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 |
ChangeEvent(EventArgs, Boolean)
Invoked when the calendar value changes, either through user selection or programmatic update.
Declaration
protected override void ChangeEvent(EventArgs args, bool isSelection = false)Parameters
| Type | Name | Description |
|---|---|---|
| System.EventArgs | args | Specifies the event arguments associated with the value change, usually from a user interaction or input. |
| System.Boolean | isSelection | Determines whether the selection was made using the mouse or keyboard. |
Overrides
Remarks
This method notifies subscribers of the ValueChange event and persists the new value if EnablePersistence is enabled. It updates the PreviousDate property to the newly selected value after change notification.
Examples
protected override void ChangeEvent(EventArgs? args, bool isSelection = false)
{
// Custom logic on value change
}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);OnAfterRenderAsync(Boolean)
Executes logic after the component has been rendered in the UI, handling post-rendering operations such as event registration and persistence.
Declaration
protected override Task OnAfterRenderAsync(bool firstRender)Parameters
| Type | Name | Description |
|---|---|---|
| System.Boolean | firstRender | If |
Returns
| Type | Description |
|---|---|
| System.Threading.Tasks.Task | A System.Threading.Tasks.Task representing the asynchronous operation performed after rendering. |
Overrides
Remarks
This method is mainly used to perform additional initialization, interact with JavaScript interop, and handle UI state persistence after the first render. It is also responsible for firing the Created event.
Examples
protected override async Task OnAfterRenderAsync(bool firstRender)
{
if (firstRender) { /* one-time logic */ }
}OnInitializedAsync()
Invoked during the initial rendering of the SfCalendar<TValue> component, enabling one-time setup and initialization logic.
Declaration
protected override Task OnInitializedAsync()Returns
| Type | Description |
|---|---|
| System.Threading.Tasks.Task | A System.Threading.Tasks.Task representing the asynchronous operation. |
Overrides
Remarks
This method is called by the Blazor framework when the component is first initialized. It is primarily used to set up component state and apply default or configured values to all internal and dependent properties before the UI is rendered.
Examples
protected override async Task OnInitializedAsync()
{
await base.OnInitializedAsync();
// Additional setup logic here
}OnParametersSetAsync()
Called by the framework when the set of component parameters has changed, allowing the component to react to dynamic property changes and state updates.
Declaration
protected override Task OnParametersSetAsync()Returns
| Type | Description |
|---|---|
| System.Threading.Tasks.Task | A System.Threading.Tasks.Task representing the asynchronous operation. |
Overrides
Remarks
Use this lifecycle method to handle logic that depends on updated parameters, such as refreshing the display or updating dependent property values. This method is executed whenever a parent component re-renders and passes new parameter values to this component.
Examples
protected override async Task OnParametersSetAsync()
{
await base.OnParametersSetAsync();
// Recompute dependent properties here
}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) });