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.

Inheritance
System.Object
SfBaseComponent
SfInputTextBase<TValue>
CalendarBase<TValue>
SfDatePicker<TValue>
SfDateTimePicker<TValue>
Inherited Members
Syncfusion.Blazor.Calendars.CalendarBase<TValue>.CurrentCulture
Syncfusion.Blazor.Calendars.CalendarBase<TValue>.IsDateOnlyType()
Syncfusion.Blazor.Calendars.CalendarBase<TValue>.IsDateTimeOffsetType()
Syncfusion.Blazor.Calendars.CalendarBase<TValue>.SetParametersAsync(Microsoft.AspNetCore.Components.ParameterView)
Syncfusion.Blazor.Inputs.SfInputTextBase<TValue>.BlurHandler(System.String, System.Boolean)
Syncfusion.Blazor.Inputs.SfInputTextBase<TValue>.ClickStopPropagation
Syncfusion.Blazor.Inputs.SfInputTextBase<TValue>.ContainerClass
Syncfusion.Blazor.Inputs.SfInputTextBase<TValue>.IsValueTemplate
Syncfusion.Blazor.Inputs.SfInputTextBase<TValue>.MouseDowSpinnerPrevent
Syncfusion.Blazor.Inputs.SfInputTextBase<TValue>.MousePreventContainer
Syncfusion.Blazor.Inputs.SfInputTextBase<TValue>.OnBlur
Syncfusion.Blazor.Inputs.SfInputTextBase<TValue>.OnChange
Syncfusion.Blazor.Inputs.SfInputTextBase<TValue>.OnFocus
Syncfusion.Blazor.Inputs.SfInputTextBase<TValue>.OnInput
Syncfusion.Blazor.Inputs.SfInputTextBase<TValue>.OnPaste
Syncfusion.Blazor.Inputs.SfInputTextBase<TValue>.PreventIconHandler
Syncfusion.Blazor.Inputs.SfInputTextBase<TValue>.RootClass
Syncfusion.Blazor.Inputs.SfInputTextBase<TValue>.SpinButton
Syncfusion.Blazor.Inputs.SfInputTextBase<TValue>.ValueExpression
Syncfusion.Blazor.Inputs.SfInputTextBase<TValue>.ValueTemplate
Namespace: Syncfusion.Blazor.Calendars
Assembly: Syncfusion.Blazor.dll
Syntax
public class SfDatePicker<TValue> : CalendarBase<TValue>, IMaskPlaceholder
Type 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()

Fields

ARIA_ACTIVE_DESCENDANT

Declaration
protected const string ARIA_ACTIVE_DESCENDANT = "aria-activedescendant"
Field Value
Type
System.String

ARIA_INVALID

Specifies the value used for the aria-invalid attribute for accessibility.

Declaration
protected const string ARIA_INVALID = "aria-invalid"
Field Value
Type Description
System.String

The attribute value string for aria-invalid.
Remarks

Used by assistive technologies to indicate that the DatePicker input is invalid.

DATE_ICON

Specifies the class name for the date icon.

Declaration
protected const string DATE_ICON = "e-date-icon e-icons"
Field Value
Type Description
System.String

The icon's CSS class string value is e-date-icon e-icons.
Remarks

Used to display a calendar icon within the DatePicker input.

ERROR_CLASS

Specifies the error class name applied to the DatePicker input when an invalid date is entered.

Declaration
protected const string ERROR_CLASS = "e-error"
Field Value
Type Description
System.String

The error class string value is e-error.
Remarks

Use this class to customize the appearance of the DatePicker in error state.

FALSE

Declaration
protected const string FALSE = "false"
Field Value
Type
System.String

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

true if the input field can be edited by the user; otherwise, false. Default value is true.
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" />

BaseFloatLabelType

Declaration
protected override FloatLabelType BaseFloatLabelType { get; set; }
Property Value
Type
FloatLabelType
Overrides
Syncfusion.Blazor.Inputs.SfInputTextBase<TValue>.BaseFloatLabelType

BaseHtmlAttributes

Declaration
protected override Dictionary<string, object> BaseHtmlAttributes { get; set; }
Property Value
Type
System.Collections.Generic.Dictionary<System.String, System.Object>
Overrides
Syncfusion.Blazor.Inputs.SfInputTextBase<TValue>.BaseHtmlAttributes

BaseInputAttributes

Declaration
protected override Dictionary<string, object> BaseInputAttributes { get; set; }
Property Value
Type
System.Collections.Generic.Dictionary<System.String, System.Object>
Overrides
Syncfusion.Blazor.Inputs.SfInputTextBase<TValue>.BaseInputAttributes

BaseIsReadOnlyInput

Declaration
protected override bool BaseIsReadOnlyInput { get; set; }
Property Value
Type
System.Boolean
Overrides
Syncfusion.Blazor.Inputs.SfInputTextBase<TValue>.BaseIsReadOnlyInput

BasePlaceholder

Declaration
protected override string BasePlaceholder { get; set; }
Property Value
Type
System.String
Overrides
Syncfusion.Blazor.Inputs.SfInputTextBase<TValue>.BasePlaceholder

BaseReadonly

Declaration
protected override bool BaseReadonly { get; set; }
Property Value
Type
System.Boolean
Overrides
Syncfusion.Blazor.Inputs.SfInputTextBase<TValue>.BaseReadonly

BaseShowClearButton

Declaration
protected override bool BaseShowClearButton { get; set; }
Property Value
Type
System.Boolean
Overrides
Syncfusion.Blazor.Inputs.SfInputTextBase<TValue>.BaseShowClearButton

BaseTabIndex

Declaration
protected override int BaseTabIndex { get; set; }
Property Value
Type
System.Int32
Overrides
Syncfusion.Blazor.Inputs.SfInputTextBase<TValue>.BaseTabIndex

BaseWidth

Declaration
protected override string BaseWidth { get; set; }
Property Value
Type
System.String
Overrides
Syncfusion.Blazor.Inputs.SfInputTextBase<TValue>.BaseWidth

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

true enables input mask rendering; otherwise, false. Default value is false.
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="Syncfusion.Blazor.Inputs.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 string representing the date format. The default format is culture-specific (M/d/yyyy for en-US).
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

true enables full screen layout for the popup; otherwise, false. Default value is false.
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 string and object containing custom HTML attributes.
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 string and object containing additional input attributes.
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 string values representing acceptable input formats. Default is null (culture-based).
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" }' />

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

true if the popup should open on input focus; otherwise, false. Default is false.
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 string representing the placeholder text. Default value is string.Empty.
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

true if the value cannot be edited; otherwise, false. Default value is true.
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" />

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

true displays the clear button; otherwise, false. Default value is false.
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

true prevents entry of invalid or out-of-range values; otherwise, false allows invalid values. Default is false.
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 int indicating the tab order. Default is 0.
Remarks

Set this property to control the keyboard tab navigation order for accessibility.

Examples
<SfDatePicker TValue="DateTime?" TabIndex="1" />

TimePart

Declaration
protected DateTime TimePart { get; set; }
Property Value
Type
System.DateTime

Width

Gets or sets the width of the SfDatePicker<TValue> component.

Declaration
public string Width { get; set; }
Property Value
Type Description
System.String

A string value specifying the width. Default value is null (auto width).
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 int representing the ZIndex of the popup. Default value is 1000.
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

ClientPopupRender()

Method to trigger the client-side actions once the popup is displayed when date icon is clicked.

Declaration
protected virtual Task ClientPopupRender()
Returns
Type Description
System.Threading.Tasks.Task

The System.Threading.Tasks.Task.

CreateMask()

Declaration
protected Task CreateMask()
Returns
Type
System.Threading.Tasks.Task

CurrentView()

Gets the current view of the calendar for the SfDatePicker<TValue> component.

Declaration
public string CurrentView()
Returns
Type Description
System.String

A string describing the current view (such as Month, Year, or Decade) of the calendar UI.
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();

FormatValue(String)

Declaration
protected override TValue FormatValue(string genericValue)
Parameters
Type Name Description
System.String genericValue
Returns
Type
TValue
Overrides
Syncfusion.Blazor.Inputs.SfInputTextBase<TValue>.FormatValue(System.String)

FormatValueAsString(TValue)

Declaration
protected override string FormatValueAsString(TValue formatValue)
Parameters
Type Name Description
TValue formatValue
Returns
Type
System.String
Overrides
Syncfusion.Blazor.Inputs.SfInputTextBase<TValue>.FormatValueAsString(TValue)

GetDefaultFormat()

Declaration
protected string GetDefaultFormat()
Returns
Type
System.String

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();

InputHandler(ChangeEventArgs)

Declaration
protected override Task InputHandler(ChangeEventArgs args)
Parameters
Type Name Description
Microsoft.AspNetCore.Components.ChangeEventArgs args
Returns
Type
System.Threading.Tasks.Task
Overrides
Syncfusion.Blazor.Inputs.SfInputTextBase<TValue>.InputHandler(Microsoft.AspNetCore.Components.ChangeEventArgs)

InvokeClearBtnEvent(EventArgs)

Declaration
protected Task InvokeClearBtnEvent(EventArgs args)
Parameters
Type Name Description
System.EventArgs args
Returns
Type
System.Threading.Tasks.Task

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);

ShowPopup(EventArgs)

Declaration
protected Task ShowPopup(EventArgs args = null)
Parameters
Type Name Description
System.EventArgs args
Returns
Type
System.Threading.Tasks.Task

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();

UpdateDateTimePopupState(Boolean)

Task used to update the popup state.

Declaration
protected virtual void UpdateDateTimePopupState(bool isOpen)
Parameters
Type Name Description
System.Boolean isOpen

true if the popup is in opened state, otherwise false.

UpdateValidateClass()

Method which updates the valid class based on the value .

Declaration
protected void UpdateValidateClass()