Class SfDatePicker<TValue>
The DatePicker is a graphical user interface component that allows users to select or enter a date value. It offers interactive and accessible features for choosing dates via keyboard, mouse, or touch input in web applications.
Implements
Inherited Members
Namespace: Syncfusion.Blazor.Toolkit.Calendars
Assembly: Syncfusion.Blazor.Toolkit.dll
Syntax
public class SfDatePicker<TValue> : CalendarBase<TValue>, IAsyncDisposable, IMaskPlaceholderType Parameters
| Name | Description |
|---|---|
| TValue | Specifies the type used by the date picker for value binding and manipulation. |
Remarks
Use the SfDatePicker<TValue> component to create a fully featured date selection UI with support for templates, formatting, validation, localization, and customization options.
Examples
This example demonstrates how to use the DatePicker.
<SfDatePicker TValue="DateTime" Placeholder="Enter date"/>Basic usage:
<SfDatePicker TValue="DateTime?" Placeholder="Select a date" />The following example demonstrates how to use the SfDatePicker<TValue> in a Blazor application.
<SfDatePicker TValue="DateTime" Placeholder="Choose a date"></SfDatePicker>Constructors
SfDatePicker()
Declaration
public SfDatePicker()Properties
AllowEdit
Gets or sets a boolean value that determines whether the SfDatePicker<TValue> allows the user to edit the value by typing in the input field, in addition to using the date picker popup.
Declaration
public bool AllowEdit { get; set; }Property Value
| Type | Description |
|---|---|
| System.Boolean |
|
Remarks
When set to false, the user can only select a date using the picker popup. Editing the value via direct text entry is disabled.
Examples
<SfDatePicker TValue="DateTime?" AllowEdit="false" />Cleared
Gets or sets the event callback that is invoked when the component value is cleared using the clear button.
Declaration
public EventCallback<ClearedEventArgs> Cleared { get; set; }Property Value
| Type | Description |
|---|---|
| Microsoft.AspNetCore.Components.EventCallback<ClearedEventArgs> | An Microsoft.AspNetCore.Components.EventCallback<> triggered after the value is cleared by the user. |
Remarks
Use this event to handle actions, such as resetting dependent fields or updating state, after the DatePicker value is cleared.
Created
Gets or sets the event callback that is invoked when the component is created.
Declaration
public EventCallback<object> Created { get; set; }Property Value
| Type | Description |
|---|---|
| Microsoft.AspNetCore.Components.EventCallback<System.Object> | An Microsoft.AspNetCore.Components.EventCallback triggered once the DatePicker component is created and ready for use. |
Remarks
Use this event to perform initialization or startup logic for the DatePicker.
DayCellRendering
Gets or sets the event callback that is invoked when each day cell of the Calendar is rendered.
Declaration
public EventCallback<RenderDayCellEventArgs> DayCellRendering { get; set; }Property Value
| Type | Description |
|---|---|
| Microsoft.AspNetCore.Components.EventCallback<RenderDayCellEventArgs> | An Microsoft.AspNetCore.Components.EventCallback<> triggered while rendering each day cell in the Calendar Popup. |
Remarks
Use this event to customize the appearance and content of individual day cells in the Calendar.
Examples
<SfDatePicker TValue="DateTime?" DayCellRendering="CellRendered">
</SfDatePicker>
@code{
private void CellRendered(RenderDayCellEventArgs args) {
args.CellData.ClassList = "e-custom-style";
}
}Destroyed
Gets or sets the event callback that is invoked when the component is destroyed.
Declaration
public EventCallback<object> Destroyed { get; set; }Property Value
| Type | Description |
|---|---|
| Microsoft.AspNetCore.Components.EventCallback<System.Object> | An Microsoft.AspNetCore.Components.EventCallback triggered just before the DatePicker component is removed from the UI. |
Remarks
Clean up resources or perform any necessary teardown logic inside this event.
EnableMask
Gets or sets a boolean value to enable or disable the use of an input mask in the SfDatePicker<TValue> component.
Declaration
public bool EnableMask { get; set; }Property Value
| Type | Description |
|---|---|
| System.Boolean |
|
Remarks
The input mask property restricts input to characters allowed by the date format, preventing unwanted characters from being typed. This helps ensure only valid date values are entered.
Examples
<SfDatePicker TValue="DateTime?" EnableMask="true" />FloatLabelType
Gets or sets the floating label behavior for the SfDatePicker<TValue> component, determining how the placeholder text is displayed.
Declaration
public FloatLabelType FloatLabelType { get; set; }Property Value
| Type | Description |
|---|---|
| FloatLabelType | A value of the FloatLabelType enum that specifies the float label mode. Default is Never. |
Remarks
This property allows you to control whether the placeholder text always floats, never floats, or floats only when the input is focused or contains a value.
Examples
<SfDatePicker TValue="DateTime?" FloatLabelType="FloatLabelType.Auto" />Format
Gets or sets the display format string used to present the selected date value in the SfDatePicker<TValue> component.
Declaration
public string Format { get; set; }Property Value
| Type | Description |
|---|---|
| System.String | A |
Remarks
By default, the component's format string depends on the current culture. To customize the display, set your desired format string.
Examples
<SfDatePicker TValue="DateTime?" Format="dd/MM/yyyy" />FullScreen
Gets or sets a boolean value indicating whether the date picker popup should be displayed in full screen mode on mobile or tablet devices.
Declaration
public bool FullScreen { get; set; }Property Value
| Type | Description |
|---|---|
| System.Boolean |
|
Remarks
Full screen layout is applicable only for mobile and tablet devices, providing a better user experience on small screens.
Examples
<SfDatePicker TValue="DateTime?" FullScreen="true" />HtmlAttributes
Gets or sets additional HTML attributes, such as style or class, that are added to the root element of the SfDatePicker<TValue> component.
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
Additional attributes can be specified inline or via the @attributes directive.
Examples
<SfDatePicker TValue="DateTime?" HtmlAttributes="@CustomAttributes" />
@code{
Dictionary<string, object> CustomAttributes = new Dictionary<string, object>
{
{ "title", "Select a Date" }
};
}InputAttributes
Gets or sets additional input attributes such as disabled or value for the root input element of the SfDatePicker<TValue>.
Declaration
public Dictionary<string, object> InputAttributes { get; set; }Property Value
| Type | Description |
|---|---|
| System.Collections.Generic.Dictionary<System.String, System.Object> | A System.Collections.Generic.Dictionary<, > of |
Remarks
If both property-specific and HTML attribute values are set for the same property, the property value takes precedence over the input attribute.
InputFormats
Gets or sets an array of input format strings used to parse input values in the SfDatePicker<TValue> component.
Declaration
public string[] InputFormats { get; set; }Property Value
| Type | Description |
|---|---|
| System.String[] | An array of |
Remarks
When both InputFormats and Format properties are specified, InputFormats takes precedence when parsing entered values. Supported C# standard and custom date formats are accepted. Parsing will try each pattern in order, successful parsing updates the value. For invalid input, the StrictMode property determines error handling: in strict mode, the value resets to previous if invalid; otherwise, it is highlighted with an error CSS class.
Examples
<SfDatePicker TValue="DateTime?" InputFormats='new string[] { "dd/MM/yyyy", "MM/dd/yyyy", "yyyy-MM-dd" }' />Navigated
Gets or sets the event callback that is invoked when the Calendar is navigated to another level or within the same view.
Declaration
public EventCallback<NavigatedEventArgs> Navigated { get; set; }Property Value
| Type | Description |
|---|---|
| Microsoft.AspNetCore.Components.EventCallback<NavigatedEventArgs> | An Microsoft.AspNetCore.Components.EventCallback<> triggered each time the view changes between year, month, or decade. |
Remarks
Use this event to capture or act on navigation between the Calendar views, such as customizing data for a specific view.
Examples
<SfDatePicker TValue="DateTime?" Navigated="@ViewNavigated">
</SfDatePicker>
@code{
private void ViewNavigated(NavigatedEventArgs args) {
Console.WriteLine(args.View);
}
}OnBlur
Gets or sets the event callback that is invoked when the component loses focus.
Declaration
public EventCallback<BlurEventArgs> OnBlur { get; set; }Property Value
| Type | Description |
|---|---|
| Microsoft.AspNetCore.Components.EventCallback<BlurEventArgs> | An Microsoft.AspNetCore.Components.EventCallback<> triggered when the input loses focus. |
Remarks
Use this event to perform custom logic when the input field loses focus, such as finalizing data entry or validation.
OnClose
Gets or sets the event callback that is invoked when the popup is closed.
Declaration
public EventCallback<PopupObjectArgs> OnClose { get; set; }Property Value
| Type | Description |
|---|---|
| Microsoft.AspNetCore.Components.EventCallback<PopupObjectArgs> | An Microsoft.AspNetCore.Components.EventCallback<> triggered when the popup is closed, either by user action or programmatically. |
Remarks
Use this event to execute custom logic after the popup closes. You can cancel closing through the event argument.
Examples
<SfDatePicker TValue="DateTime?" OnClose="@PopupClose">
</SfDatePicker>
@code{
private void PopupClose(PopupObjectArgs args) {
args.Cancel = true;
}
}OnFocus
Gets or sets the event callback that is invoked when the component receives focus.
Declaration
public EventCallback<FocusEventArgs> OnFocus { get; set; }Property Value
| Type | Description |
|---|---|
| Microsoft.AspNetCore.Components.EventCallback<FocusEventArgs> | An Microsoft.AspNetCore.Components.EventCallback<> triggered when the component input receives keyboard or mouse focus. |
Remarks
Use this event to respond to focus changes or update UI highlights as required.
OnInput
Gets or sets an event callback that is invoked when the user inputs or modifies the value in the DatePicker.
Declaration
public EventCallback<ChangeEventArgs> OnInput { get; set; }Property Value
| Type | Description |
|---|---|
| Microsoft.AspNetCore.Components.EventCallback<Microsoft.AspNetCore.Components.ChangeEventArgs> | An Microsoft.AspNetCore.Components.EventCallback that receives a Microsoft.AspNetCore.Components.ChangeEventArgs containing the input value information. |
Remarks
This event is triggered on each user input as they type or modify the date value directly in the input field.
Examples
<SfDatePicker TValue="DateTime?" OnInput="@OnInput">
</SfDatePicker>
@code{
private void OnInput(ChangeEventArgs args) {
Console.WriteLine("Input value changed");
}
}OnOpen
Gets or sets the event callback that is invoked when the popup is opened.
Declaration
public EventCallback<PopupObjectArgs> OnOpen { get; set; }Property Value
| Type | Description |
|---|---|
| Microsoft.AspNetCore.Components.EventCallback<PopupObjectArgs> | An Microsoft.AspNetCore.Components.EventCallback<> triggered when the picker popup is opened. |
Remarks
Use this event to customize the popup prior to it being displayed, such as modifying content or cancelling the open action.
Examples
<SfDatePicker TValue="DateTime?" OnOpen="@PopupOpen">
</SfDatePicker>
@code{
private void PopupOpen(PopupObjectArgs args) {
args.Cancel = true;
}
}OpenOnFocus
Gets or sets a boolean value to determine whether the popup calendar opens automatically when the input element receives focus.
Declaration
public bool OpenOnFocus { get; set; }Property Value
| Type | Description |
|---|---|
| System.Boolean |
|
Remarks
Enabling this property can enhance user experience by triggering the date picker popup as soon as the user clicks or tabs into the input element. This is especially useful in scenarios that require quick, single-step date selection.
Examples
<SfDatePicker TValue="DateTime?" OpenOnFocus="true" />Placeholder
Gets or sets the placeholder text displayed in the input box until the user enters a value or focuses the SfDatePicker<TValue>.
Declaration
public string Placeholder { get; set; }Property Value
| Type | Description |
|---|---|
| System.String | A |
Remarks
Placeholder display behavior may depend on the FloatLabelType property value.
Examples
<SfDatePicker TValue="DateTime?" Placeholder="Select your birthday..." />Readonly
Gets or sets a boolean value indicating whether text entry is read-only in the SfDatePicker<TValue> component.
Declaration
public bool Readonly { get; set; }Property Value
| Type | Description |
|---|---|
| System.Boolean |
|
Remarks
When Readonly is enabled, the input field cannot be changed and the date picker popup will not open.
Examples
<SfDatePicker TValue="DateTime?" Readonly="true" />Selected
Gets or sets the event callback that is invoked after selecting the value from the component.
Declaration
public EventCallback<SelectedEventArgs<TValue>> Selected { get; set; }Property Value
| Type | Description |
|---|---|
| Microsoft.AspNetCore.Components.EventCallback<SelectedEventArgs<TValue>> | An Microsoft.AspNetCore.Components.EventCallback<> of type |
Remarks
This event occurs after the user selects a value from the Calendar, but before the value is set. Use this event for custom actions such as formatting or validation prior to assignment.
Examples
<SfDatePicker TValue="DateTime?" Selected="@ValueSelected">
</SfDatePicker>
@code{
private void ValueSelected(SelectedEventArgs<DateTime?> args) {
Console.WriteLine(args.Value);
}
}ShowClearButton
Gets or sets a boolean value indicating whether a clear button is shown in the SfDatePicker<TValue> component.
Declaration
public bool ShowClearButton { get; set; }Property Value
| Type | Description |
|---|---|
| System.Boolean |
|
Remarks
When the clear button is displayed, users can quickly reset the input value to its default state.
Examples
<SfDatePicker TValue="DateTime?" ShowClearButton="true" />StrictMode
Gets or sets a boolean value that determines whether only valid date values within a specified range can be entered. If set to true, invalid or out-of-range values are disallowed or reset.
Declaration
public bool StrictMode { get; set; }Property Value
| Type | Description |
|---|---|
| System.Boolean |
|
Remarks
In strict mode, invalid dates revert to the previous valid value. Otherwise, input errors are visually highlighted.
Examples
<SfDatePicker TValue="DateTime?" StrictMode="true" />TabIndex
Gets or sets the tab index order of the SfDatePicker<TValue> component.
Declaration
public int TabIndex { get; set; }Property Value
| Type | Description |
|---|---|
| System.Int32 | An |
Remarks
Set this property to control the keyboard tab navigation order for accessibility.
Examples
<SfDatePicker TValue="DateTime?" TabIndex="1" />ValueChange
Gets or sets the event callback that is invoked when the component value is changed.
Declaration
public EventCallback<ChangedEventArgs<TValue>> ValueChange { get; set; }Property Value
| Type | Description |
|---|---|
| Microsoft.AspNetCore.Components.EventCallback<ChangedEventArgs<TValue>> | An Microsoft.AspNetCore.Components.EventCallback<> of type |
Remarks
Use this event to respond to changes to the input value, either from user interaction or programmatic changes. The event provides the new value in the event arguments.
Examples
<SfDatePicker TValue="DateTime?" ValueChange="@ValueChange">
</SfDatePicker>
@code{
private void ValueChange(ChangedEventArgs<DateTime?> args) {
Console.WriteLine(args.Value);
}
}Width
Gets or sets the width of the SfDatePicker<TValue> component.
Declaration
public string Width { get; set; }Property Value
| Type | Description |
|---|---|
| System.String | A |
Remarks
Set this property to specify a custom width for the control in CSS units.
Examples
<SfDatePicker TValue="DateTime?" Width="280px" />ZIndex
Gets or sets the CSS Z-Index value for the popup associated with the SfDatePicker<TValue> component.
Declaration
public int ZIndex { get; set; }Property Value
| Type | Description |
|---|---|
| System.Int32 | An |
Remarks
The ZIndex controls the stacking order of the popup on the page. Increasing the value brings the popup above more elements.
Examples
<SfDatePicker TValue="DateTime?" ZIndex="2000" />Methods
BuildRenderTree(RenderTreeBuilder)
Declaration
protected override void BuildRenderTree(RenderTreeBuilder __builder)Parameters
| Type | Name | Description |
|---|---|---|
| Microsoft.AspNetCore.Components.Rendering.RenderTreeBuilder | __builder |
CurrentView()
Gets the current view of the calendar for the SfDatePicker<TValue> component.
Declaration
public string CurrentView()Returns
| Type | Description |
|---|---|
| System.String | A |
Remarks
This method reports the current view in the popup calendar, which is useful for UI automation or debugging.
Examples
string currentView = datePickerRef.CurrentView();FocusAsync()
Sets focus to the SfDatePicker<TValue> component for user interaction.
Declaration
public Task FocusAsync()Returns
| Type | Description |
|---|---|
| System.Threading.Tasks.Task | A System.Threading.Tasks.Task representing the asynchronous operation that sets focus to the component. |
Remarks
Call this method to programmatically set input focus on the DatePicker, for example after form submission or to assist keyboard navigation.
Examples
await datePickerRef.FocusAsync();FocusOutAsync()
Removes input focus from the SfDatePicker<TValue> component if it is currently focused.
Declaration
public Task FocusOutAsync()Returns
| Type | Description |
|---|---|
| System.Threading.Tasks.Task | A System.Threading.Tasks.Task representing the asynchronous operation that removes focus from the component. |
Remarks
Use this method to programmatically blur or remove focus from the DatePicker control, such as when navigating away or validating input.
Examples
await datePickerRef.FocusOutAsync();GetPersistDataAsync()
Gets the persisted state properties of the SfDatePicker<TValue> for maintaining component state.
Declaration
public Task<string> GetPersistDataAsync()Returns
| Type | Description |
|---|---|
| System.Threading.Tasks.Task<System.String> | A System.Threading.Tasks.Task<> representing the asynchronous operation that returns persisted state information as a JSON string. |
Remarks
Use this method to fetch the component's persisted state, typically for state handling across reloads or navigation.
Examples
string persistedData = await datePickerRef.GetPersistDataAsync();HidePopupAsync(EventArgs)
Hides the calendar popup of the SfDatePicker<TValue> component.
Declaration
public Task HidePopupAsync(EventArgs args = null)Parameters
| Type | Name | Description |
|---|---|---|
| System.EventArgs | args | The event arguments that trigger hiding the popup. Optional. |
Returns
| Type | Description |
|---|---|
| System.Threading.Tasks.Task | A System.Threading.Tasks.Task representing the asynchronous operation to hide the popup calendar. |
Remarks
This method closes the popup calendar if it is currently open, restoring the component to its normal state.
Examples
await datePickerRef.HidePopupAsync();NavigateAsync(CalendarView, TValue)
Navigates to the specified view (month, year, or decade) and date in the calendar for the SfDatePicker<TValue> component.
Declaration
public Task NavigateAsync(CalendarView view, TValue date)Parameters
| Type | Name | Description |
|---|---|---|
| CalendarView | view | The target CalendarView (such as Month, Year, or Decade). |
| TValue | date | The focused date to display in the given view. |
Returns
| Type | Description |
|---|---|
| System.Threading.Tasks.Task | A System.Threading.Tasks.Task representing the asynchronous navigation operation. |
Remarks
This method programmatically changes the calendar UI to display the specified view and highlights the chosen date. Use it for advanced navigation scenarios.
Examples
await datePickerRef.NavigateAsync(CalendarView.Year, DateTime.Now);ShowPopupAsync(EventArgs)
Opens the popup calendar associated with the SfDatePicker<TValue> component.
Declaration
public Task ShowPopupAsync(EventArgs args = null)Parameters
| Type | Name | Description |
|---|---|---|
| System.EventArgs | args | The event arguments that trigger the popup. Optional. |
Returns
| Type | Description |
|---|---|
| System.Threading.Tasks.Task | A System.Threading.Tasks.Task representing the asynchronous operation to show the calendar popup. |
Remarks
This method opens the calendar popup, allowing the user to select a date from a visual calendar interface. If the DatePicker is not enabled, the popup will not display.
Examples
await datePickerRef.ShowPopupAsync();