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
object
ComponentBase
OwningComponentBase
SfOwningComponentBase
SfBaseComponent
SfInputTextBase<TValue>
CalendarBase<TValue>
SfDatePicker<TValue>
SfDateTimePicker<TValue>
Implements
Inherited Members
Namespace: Syncfusion.Blazor.Calendars
Assembly: Syncfusion.Blazor.dll
Syntax
public class SfDatePicker<TValue> : CalendarBase<TValue>, IComponent, IHandleEvent, IHandleAfterRender, IDisposable
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
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
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
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
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
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
[Parameter]
public bool AllowEdit { get; set; }
Property Value
Type Description
bool

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

Gets or sets the floating label behavior of the input component that determines how the placeholder text is displayed.

Declaration
protected override FloatLabelType BaseFloatLabelType { get; set; }
Property Value
Type Description
FloatLabelType

A FloatLabelType enumeration value that specifies the floating label behavior. The default value depends on the specific input component implementation.
Overrides
Remarks

The floating label behavior controls how the placeholder text is presented to the user:

  • NeverThe label never floats and remains as a standard placeholder text within the input field.
  • AlwaysThe label is always positioned above the input field, providing a consistent visual layout.
  • AutoThe label dynamically floats above the input field when the component receives focus or contains a value, creating an animated transition effect.

BaseHtmlAttributes

Gets or sets additional HTML attributes to be applied to the input component's container element.

Declaration
protected override Dictionary<string, object> BaseHtmlAttributes { get; set; }
Property Value
Type Description
Dictionary<string, object>

A Dictionary<TKey, TValue> containing key-value pairs of HTML attributes, or null if no additional attributes are specified.
Overrides
Remarks

Use this property to add custom HTML attributes such as data attributes, accessibility attributes, or styling classes to the component's container. Common attributes like 'class', 'style', and 'title' are handled specially and may be applied to different elements within the component structure.

BaseInputAttributes

Gets or sets additional HTML attributes to be applied specifically to the input element itself.

Declaration
protected override Dictionary<string, object> BaseInputAttributes { get; set; }
Property Value
Type Description
Dictionary<string, object>

A Dictionary<TKey, TValue> containing key-value pairs of HTML attributes. The default value is an empty dictionary.
Overrides
Remarks

This property allows direct customization of the underlying input element with additional HTML attributes. Attributes set here will be applied directly to the input tag, enabling fine-grained control over input behavior and appearance.

BaseIsReadOnlyInput

Gets or sets a value indicating whether the input element itself should be marked as read-only.

Declaration
protected override bool BaseIsReadOnlyInput { get; set; }
Property Value
Type Description
bool

true if the input element is read-only; otherwise, false. The default value depends on the specific input component implementation.
Overrides
Remarks

This property specifically controls the read-only attribute on the underlying HTML input element, which may behave differently from the component-level BaseReadonly property.

BasePlaceholder

Gets or sets the placeholder text displayed in the input when no value is present.

Declaration
protected override string BasePlaceholder { get; set; }
Property Value
Type Description
string

A string representing the placeholder text, or null if no placeholder is specified.
Overrides
Remarks

The placeholder provides a hint to users about the expected input format or content. This text is automatically hidden when the input receives focus or contains a value.

BaseReadonly

Gets or sets a value indicating whether the input component is in read-only mode.

Declaration
protected override bool BaseReadonly { get; set; }
Property Value
Type Description
bool

true if the input is read-only; otherwise, false. The default value depends on the specific input component implementation.
Overrides
Remarks

When in read-only mode, users can view and select the content but cannot modify it. The input will still receive focus and trigger events, but user input will be prevented.

BaseShowClearButton

Gets or sets a value indicating whether a clear button should be displayed to allow users to quickly clear the input value.

Declaration
protected override bool BaseShowClearButton { get; set; }
Property Value
Type Description
bool

true if the clear button should be shown; otherwise, false. The default value depends on the specific input component implementation.
Overrides
Remarks

When enabled, a clear button appears within the input field when it contains a value, allowing users to quickly clear the content. The button is automatically hidden when the input is empty, disabled, or read-only.

BaseTabIndex

Gets or sets the tab index of the input component for keyboard navigation.

Declaration
protected override int BaseTabIndex { get; set; }
Property Value
Type Description
int

An integer representing the tab order. Positive values indicate the explicit tab order, 0 means the element is focusable in document order, and negative values remove the element from tab navigation.
Overrides
Remarks

This property controls the order in which the component receives focus during keyboard navigation. When the component is disabled, the tab index is automatically set to -1 to remove it from the tab sequence.

BaseWidth

Gets or sets the width of the input component.

Declaration
protected override string BaseWidth { get; set; }
Property Value
Type Description
string

A string representing the width in CSS units (e.g., "100px", "50%"), or null to use the default width.
Overrides
Remarks

This property accepts any valid CSS width value including pixels, percentages, em units, etc. The width is applied to the component's container element to control the overall size.

EnableMask

Gets or sets a boolean value to enable or disable the use of an input mask in the SfDatePicker<TValue> component.

Declaration
[Parameter]
public bool EnableMask { get; set; }
Property Value
Type Description
bool

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
[Parameter]
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
[Parameter]
public string Format { get; set; }
Property Value
Type Description
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
[Parameter]
public bool FullScreen { get; set; }
Property Value
Type Description
bool

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
[Parameter]
public Dictionary<string, object> HtmlAttributes { get; set; }
Property Value
Type Description
Dictionary<string, object>

A Dictionary<TKey, TValue> 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
[Parameter(CaptureUnmatchedValues = true)]
public Dictionary<string, object> InputAttributes { get; set; }
Property Value
Type Description
Dictionary<string, object>

A Dictionary<TKey, TValue> 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
[Parameter]
public string[] InputFormats { get; set; }
Property Value
Type Description
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
[Parameter]
public bool OpenOnFocus { get; set; }
Property Value
Type Description
bool

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
[Parameter]
public string Placeholder { get; set; }
Property Value
Type Description
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
[Parameter]
public bool Readonly { get; set; }
Property Value
Type Description
bool

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
[Parameter]
public bool ShowClearButton { get; set; }
Property Value
Type Description
bool

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
[Parameter]
public bool StrictMode { get; set; }
Property Value
Type Description
bool

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
[Parameter]
public int TabIndex { get; set; }
Property Value
Type Description
int

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
DateTime

Width

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

Declaration
[Parameter]
public string Width { get; set; }
Property Value
Type Description
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
[Parameter]
public int ZIndex { get; set; }
Property Value
Type Description
int

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
RenderTreeBuilder __builder
Overrides

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
Task

The Task.

CreateMask()

Declaration
protected Task CreateMask()
Returns
Type
Task

CurrentView()

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

Declaration
public string CurrentView()
Returns
Type Description
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
Task

A 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
Task

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

Converts a string value to the strongly-typed value expected by the component.

Declaration
protected override TValue FormatValue(string genericValue)
Parameters
Type Name Description
string genericValue

The string value to be converted.
Returns
Type Description
TValue

A value of type TValue parsed from the string, or the default value if the string is null or empty.
Overrides
Remarks

This virtual method provides the default parsing behavior and can be overridden in derived classes to implement custom parsing logic, validation, or type-specific conversion rules.

FormatValueAsString(TValue)

Converts a strongly-typed value to its string representation for display purposes.

Declaration
protected override string FormatValueAsString(TValue formatValue)
Parameters
Type Name Description
TValue formatValue

The value to be formatted as a string.
Returns
Type Description
string

A string representation of the value, or null if the value is null.
Overrides
Remarks

This virtual method provides the default string formatting behavior and can be overridden in derived classes to implement custom formatting logic, such as number formatting, date formatting, or cultural considerations.

GetDefaultFormat()

Declaration
protected string GetDefaultFormat()
Returns
Type
string

GetPersistDataAsync()

Gets the persisted state properties of the SfDatePicker<TValue> for maintaining component state.

Declaration
public Task<string> GetPersistDataAsync()
Returns
Type Description
Task<string>

A Task<TResult> 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
EventArgs args

The event arguments that trigger hiding the popup. Optional.
Returns
Type Description
Task

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

Provides a virtual method for derived classes to implement custom input handling logic.

Declaration
protected override Task InputHandler(ChangeEventArgs args)
Parameters
Type Name Description
ChangeEventArgs args

The change event arguments containing the input data, or null if no data is available.
Returns
Type Description
Task

A Task that represents the asynchronous input handling operation.
Overrides
Remarks

This virtual method serves as an extension point for derived classes to implement component-specific input processing logic while maintaining the base class's standard input handling behavior.

InvokeClearBtnEvent(EventArgs)

Declaration
protected Task InvokeClearBtnEvent(EventArgs args)
Parameters
Type Name Description
EventArgs args
Returns
Type
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
Task

A 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
EventArgs args
Returns
Type
Task

ShowPopupAsync(EventArgs)

Opens the popup calendar associated with the SfDatePicker<TValue> component.

Declaration
public Task ShowPopupAsync(EventArgs args = null)
Parameters
Type Name Description
EventArgs args

The event arguments that trigger the popup. Optional.
Returns
Type Description
Task

A 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(bool)

Task used to update the popup state.

Declaration
protected virtual void UpdateDateTimePopupState(bool isOpen)
Parameters
Type Name Description
bool 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()

Implements