Class SfDateRangePicker<TValue>

The DateRangePicker is a graphical user interface component that allows user to select the date range from the calendar.

Inheritance
object
ComponentBase
OwningComponentBase
SfOwningComponentBase
SfBaseComponent
SfInputTextBase<TValue>
CalendarBase<TValue>
SfDateRangePicker<TValue>
Implements
Inherited Members
Namespace: Syncfusion.Blazor.Calendars
Assembly: Syncfusion.Blazor.dll
Syntax
public class SfDateRangePicker<TValue> : CalendarBase<TValue>, IComponent, IHandleEvent, IHandleAfterRender, IDisposable, IDateRangePicker
Type Parameters
Name Description
TValue

Specifies the type of SfDateRangePicker<TValue>.
Remarks

The DateRangePicker component supports various date formats, localization, validation, and preset date ranges. It provides a popup calendar interface for easy date selection and supports both manual input and calendar-based selection. The component inherits from CalendarBase<T> and implements IDateRangePicker.

Examples
<SfDateRangePicker TValue="DateTime?" Placeholder="Select a Range"></SfDateRangePicker>

The following example demonstrates how to create a basic DateRangePicker component.

<SfDateRangePicker TValue="DateTime" StartDate="DateTime.Now" EndDate="DateTime.Now.AddDays(7)" />

Constructors

SfDateRangePicker()

Declaration
public SfDateRangePicker()

Properties

AllowEdit

Gets or sets a value indicating whether the user can change the value by typing. When set to false, the value can only be changed via the picker.

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

true if the DateRangePicker value can be edited, otherwise false. The default value is true.
Remarks

Set this property to false to prevent users from typing in the input field.

Examples
<SfDateRangePicker TValue="DateTime?" AllowEdit="false"></SfDateRangePicker>

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.

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.

EndDate

Gets or sets the end date of the date range selection.

Declaration
[Parameter]
public TValue EndDate { get; set; }
Property Value
Type Description
TValue

The end date of the date range selection.
Remarks

This property can be used for two-way binding.

Examples
<SfDateRangePicker @bind-EndDate="EndDateValue" TValue="DateTime?"></SfDateRangePicker>

@code {
   public DateTime? EndDateValue { get; set; } = new DateTime(2023, 1, 20);
}

EndDateChanged

Triggers when the end date of the DateRangePicker is changed.

Declaration
[Parameter]
public EventCallback<TValue> EndDateChanged { get; set; }
Property Value
Type
EventCallback<TValue>
Remarks

This event can be used to perform actions when the end date is changed.

Examples
<SfDateRangePicker TValue="DateTime?">
    <DateRangePickerEvents TValue="DateTime?" EndDateChanged="@EndDateChangedHandler"></DateRangePickerEvents>
</SfDateRangePicker>

@code {
    public void EndDateChangedHandler(DateTime? args)
    {
        // Your logic here
    }
}

EndDateExpression

Gets or sets the expression for defining the end date of the bound.

Declaration
[Parameter]
public Expression<Func<TValue>> EndDateExpression { get; set; }
Property Value
Type Description
Expression<Func<TValue>>

An expression that defines the end date of the bound.
Remarks

This property is used to bind a specific field of a model class to the EndDate of the DateRangePicker.

Examples
<SfDateRangePicker @bind-StartDate="StartDateValue" @bind-EndDate="EndDateValue" TValue="DateTime?"></SfDateRangePicker>

@code {
   public DateTime? StartDateValue { get; set; } = new DateTime(2023, 1, 10);
   public DateTime? EndDateValue { get; set; } = new DateTime(2023, 1, 20);
}

FloatLabelType

Gets or sets the floating label behavior of the DateRangePicker that the placeholder text floats above the DateRangePicker based on the following values.

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

The floating label behavior of the DateRangePicker. The possible values are:

  • NeverThe label never floats.
  • AlwaysThe label always floats.
  • AutoThe label floats when the input is focused or has a value.
Remarks

This property determines how the placeholder text interacts with the input field.

Examples
<SfDateRangePicker TValue="DateTime?" FloatLabelType="FloatLabelType.Always" Placeholder="Select a Date Range"></SfDateRangePicker>

Format

Gets or sets the format for the start and end date strings.

Declaration
[Parameter]
public string Format { get; set; }
Property Value
Type Description
string

A string that specifies the date format. The default format is based on the culture.
Remarks

You can set formats like "dd/MM/yyyy hh:mm". By default, the format is culture-dependent, e.g., "M/d/yyyy" for en-US.

Examples
<SfDateRangePicker TValue="DateTime?" Format="yyyy-MM-dd"></SfDateRangePicker>

FullScreen

Gets or sets a boolean value that indicates whether to enable a full-screen layout for the DateRangePicker component popup in mobile devices.

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

true to enable a full-screen layout for the popup on mobile devices; otherwise, false. The default value is false.
Remarks

The FullScreen property is applicable for mobile and tablet devices only.

Examples
<SfDateRangePicker TValue="DateTime?" FullScreen="true"></SfDateRangePicker>

HtmlAttributes

Gets or sets additional HTML attributes such as styles, class, and more to the root element.

Declaration
[Parameter]
public Dictionary<string, object> HtmlAttributes { get; set; }
Property Value
Type Description
Dictionary<string, object>

A dictionary of additional HTML attributes for the root element of the DateRangePicker.
Remarks

If you have configured both this property and an equivalent HTML attribute, the component will prioritize the property value.

Examples
<SfDateRangePicker TValue="DateTime?" HtmlAttributes="@(new Dictionary<string, object>() { { "class", "custom-class" } })"></SfDateRangePicker>

InputAttributes

Gets or sets additional input attributes such as disabled, value, and more to the root element.

Declaration
[Parameter(CaptureUnmatchedValues = true)]
public Dictionary<string, object> InputAttributes { get; set; }
Property Value
Type Description
Dictionary<string, object>

A dictionary containing additional input attributes that can be added to the root element, such as disabled or value.
Remarks

If you have configured both this property and an equivalent input attribute, the component will prioritize the property value.

Examples
<SfDateRangePicker TValue="DateTime?" InputAttributes="@(new Dictionary<string, object>() { { "aria-label", "date range picker" } })"></SfDateRangePicker>

InputFormats

Gets or sets an array of input formats to be used for parsing date values in the SfDateRangePicker<TValue> component.

Declaration
[Parameter]
public string[] InputFormats { get; set; }
Property Value
Type Description
string[]

An array of strings representing the acceptable input formats for date values. The default value is null.
Remarks

This property allows the SfDateRangePicker<TValue> to interpret typed date values using a specified array of formats.
The formats can include both standard and custom formats supported in C#. When both InputFormats and Format properties are specified, the InputFormats property takes priority. If only InputFormats is specified, parsing will be attempted using the formats provided in the array.
If neither property is specified, the default behavior remains unchanged.
The parsing logic prioritizes the formats in the order they are specified in the InputFormats array.
If a successful parsing occurs, the SfDateRangePicker<TValue> updates its value accordingly. Error handling is controlled by the StrictMode property, allowing for different user experiences in case of invalid input.

Examples

The following example demonstrates how to set the InputFormats property to accept multiple date formats:

<SfDateRangePicker InputFormats='new string[] { "dd/MM/yyyy", "MM/dd/yyyy", "yyyy-MM-dd" }' TValue="DateTime?" />

MaxDays

Gets or sets the maximum number of days that can be selected in a date range.

Declaration
[Parameter]
public int? MaxDays { get; set; }
Property Value
Type Description
int?

An integer representing the maximum span of days allowed in a date range selection.
Remarks

This property helps enforce limits on the duration of the selected date range.

Examples
<SfDateRangePicker TValue="DateTime?" MaxDays="10"></SfDateRangePicker>

MinDays

Gets or sets the minimum number of days that can be selected in a date range.

Declaration
[Parameter]
public int? MinDays { get; set; }
Property Value
Type Description
int?

An integer representing the minimum span of days allowed in a date range selection.
Remarks

This property helps enforce a minimum duration for the selected date range.

Examples
<SfDateRangePicker TValue="DateTime?" MinDays="3"></SfDateRangePicker>

OpenOnFocus

Gets or sets a value indicating whether the DateRangePicker popup opens automatically when the input field receives focus.

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

true if the DateRangePicker popup should open on input focus; otherwise, false. The default is false.
Remarks

Use this property to improve user experience by automatically showing the DateRangePicker popup when the user clicks or tabs into the input field. This is particularly useful for interfaces where quick access to date selection is desirable.

Examples
<SfDateRangePicker OpenOnFocus="true" TValue="DateTime?" ></SfDateRangePicker>

Placeholder

Gets or sets the text that is shown as a hint or placeholder until the user focuses or enters a value in the DateRangePicker.

Declaration
[Parameter]
public string Placeholder { get; set; }
Property Value
Type Description
string

A string that will be displayed as a placeholder.
Remarks

The behavior of this property depends on the FloatLabelType property.

Examples
<SfDateRangePicker TValue="DateTime?" Placeholder="Select a date range"></SfDateRangePicker>

Presets

Gets or sets the list of presets for the DateRangePicker popup.

Declaration
[Parameter]
public List<Presets> Presets { get; set; }
Property Value
Type Description
List<Presets>

A list of Presets objects. The default value is an empty list.
Remarks

Presets provide predefined date ranges that users can select.

Examples
<SfDateRangePicker TValue="DateTime?">
    <DateRangePickerPresets>
        <Preset Label="Today" Start="DateTime.Now.Date" End="DateTime.Now.Date"></Preset>
    </DateRangePickerPresets>
</SfDateRangePicker>

Readonly

Gets or sets a value indicating whether the DateRangePicker is in a read-only state.

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

true if the DateRangePicker is read-only; otherwise, false. The default is false.
Remarks

When this property is set to true, the user cannot change the value.

Examples
<SfDateRangePicker TValue="DateTime?" Readonly="true"></SfDateRangePicker>

RootClass

Gets or sets the base CSS classes applied to the input component's root element.

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

A string containing the fundamental CSS classes for the component. The default value is "e-control e-textbox e-lib".
Overrides
Syncfusion.Blazor.Inputs.SfInputTextBase<TValue>.RootClass
Remarks

This property defines the core CSS classes that establish the component's base appearance and behavior. These classes are typically combined with additional state and configuration classes during rendering.

Separator

Gets or sets the string that separates the start and end date strings.

Declaration
[Parameter]
public string Separator { get; set; }
Property Value
Type Description
string

A string used as a separator. The default value is "-".
Remarks

This string is displayed between the start and end dates in the input field.

Examples
<SfDateRangePicker TValue="DateTime?" Separator="to"></SfDateRangePicker>

ShowClearButton

Gets or sets a value indicating whether to show the clear icon in the DateRangePicker.

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

true to show the clear icon; otherwise, false. The default value is true.
Remarks

The clear icon allows users to easily clear the selected date range.

Examples
<SfDateRangePicker TValue="DateTime?" ShowClearButton="true"></SfDateRangePicker>

StartDate

Gets or sets the start date of the date range selection.

Declaration
[Parameter]
public TValue StartDate { get; set; }
Property Value
Type Description
TValue

Accepts the start date of the date range selection, represented as a value of type TValue.
Remarks

This property can be used for two-way binding.

Examples
<SfDateRangePicker @bind-StartDate="StartDateValue" TValue="DateTime?"></SfDateRangePicker>

@code {
   public DateTime? StartDateValue { get; set; } = new DateTime(2023, 1, 10);
}

StartDateExpression

Gets or sets the expression for defining the start date of the bound.

Declaration
[Parameter]
public Expression<Func<TValue>> StartDateExpression { get; set; }
Property Value
Type Description
Expression<Func<TValue>>

An expression that defines the start date of the bound.
Remarks

This property is used to bind a specific field of a model class to the StartDate of the DateRangePicker.

Examples
<SfDateRangePicker @bind-StartDate="StartDateValue" @bind-EndDate="EndDateValue" TValue="DateTime?"></SfDateRangePicker>

@code {
   public DateTime? StartDateValue { get; set; } = new DateTime(2023, 1, 10);
   public DateTime? EndDateValue { get; set; } = new DateTime(2023, 1, 20);
}

StrictMode

Gets or sets a value indicating whether the DateRangePicker should operate in strict mode.

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

true to prevent entering an invalid date; otherwise, false to allow invalid or out-of-range values with a highlighted error class. The default is false.
Remarks

When in strict mode, only valid date values within the specified range are allowed, and any invalid input will be reset to the previous value.

Examples
<SfDateRangePicker TValue="DateTime?" StrictMode="true"></SfDateRangePicker>

Value

Gets or sets the selected date of the Calendar.

Declaration
public object Value { get; set; }
Property Value
Type Description
object

Accepts the selected date of calendar.
Remarks

For the DateRangePicker, this property is not the primary way to set the selected range. Use StartDate and EndDate instead.

ValueChanged

Specifies the callback to trigger when the value changes.

Declaration
public EventCallback<object> ValueChanged { get; set; }
Property Value
Type
EventCallback<object>
Remarks

For the DateRangePicker, this event is not the primary way to handle value changes. Use Syncfusion.Blazor.Calendars.SfDateRangePicker<TValue>.StartDateChanged and EndDateChanged instead.

ValueExpression

Gets or sets the expression for defining the value of the bound.

Declaration
public Expression<Func<object>> ValueExpression { get; set; }
Property Value
Type Description
Expression<Func<object>>

An expression that defines the value of the bound.
Remarks

This property is not typically used for the DateRangePicker. Use StartDateExpression and EndDateExpression instead.

Width

Gets or sets the width of the DateRangePicker component.

Declaration
[Parameter]
public string Width { get; set; }
Property Value
Type Description
string

A string that defines the width.
Remarks

The width can be specified in pixels or percentages.

Examples
<SfDateRangePicker TValue="DateTime?" Width="250px"></SfDateRangePicker>

ZIndex

Gets or sets the z-index value of the DateRangePicker popup element.

Declaration
[Parameter]
public int ZIndex { get; set; }
Property Value
Type Description
int

An integer that specifies the z-index. The default value is 1000.
Remarks

This property is useful for controlling the stacking order of the popup element.

Examples
<SfDateRangePicker TValue="DateTime?" ZIndex="1200"></SfDateRangePicker>

Methods

BuildRenderTree(RenderTreeBuilder)

Declaration
protected override void BuildRenderTree(RenderTreeBuilder __builder)
Parameters
Type Name Description
RenderTreeBuilder __builder
Overrides

ChangeHandler(ChangeEventArgs)

Handles change events when the DateRangePicker input value changes.

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

The ChangeEventArgs containing the change event information.
Returns
Type Description
Task

A Task representing the asynchronous operation.
Overrides
Remarks

This method processes value changes from user input or programmatic updates, excluding clear operations. It updates the current value string to reflect the new input state.

CurrentView()

Gets the current view of the calendar.

Declaration
public string CurrentView()
Returns
Type Description
string

A string representing the current view of the calendar, such as "Month", "Year", or "Decade".
Remarks

This method returns the name of the current view being displayed in the calendar. For example, if the calendar is showing the monthly view, it will return "Month".

FocusAsync()

Sets focus on the DateRangePicker component for interaction.

Declaration
public Task FocusAsync()
Returns
Type Description
Task

A Task that represents the asynchronous operation.
Remarks

This method allows you to programmatically focus on the DateRangePicker, enabling user interaction and input.

FocusHandler(FocusEventArgs)

Handles the focus event when the DateRangePicker input receives focus.

Declaration
protected override Task FocusHandler(FocusEventArgs args)
Parameters
Type Name Description
FocusEventArgs args

The FocusEventArgs containing focus event information.
Returns
Type Description
Task

A Task representing the asynchronous operation.
Overrides
Remarks

This method triggers focus-related actions such as invoking focus event handlers, adjusting float label behavior, and optionally opening the popup if OpenOnFocus is enabled. It ensures proper focus management and user experience.

FocusOutAsync()

Removes focus from the DateRangePicker component if it is in a focused state.

Declaration
public Task FocusOutAsync()
Returns
Type Description
Task

A Task that represents the asynchronous operation.
Remarks

This method is used to programmatically remove focus from the DateRangePicker, which can be useful for managing user input flow.

FocusOutHandler(FocusEventArgs)

Handles the blur event when the DateRangePicker input loses focus.

Declaration
protected override Task FocusOutHandler(FocusEventArgs args)
Parameters
Type Name Description
FocusEventArgs args

The FocusEventArgs containing focus event information.
Returns
Type Description
Task

A Task representing the asynchronous operation.
Overrides
Remarks

This method processes focus out events by validating input values, updating component state, adjusting visual elements, and triggering blur event handlers. It ensures data integrity when the user navigates away from the input.

FormatValue(string?)

Formats and validates the input string value into the appropriate date range format.

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

The string value to format and validate. If null, uses the component's current input value.
Returns
Type Description
TValue

The default value of type TValue, as this method updates internal properties rather than returning a formatted value.
Overrides
Remarks

This method parses the input string to extract start and end date values, validates them against the component's constraints, and updates the internal StartValue and EndValue properties accordingly.

FormatValueAsString(TValue)

Formats the specified date range value as a string representation.

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

The date range value to format. This parameter is not directly used as the method formats the current StartDate and EndDate values.
Returns
Type Description
string

A string representing the formatted date range, or the current formatted date value, or default if no valid range exists.
Overrides
Remarks

This method converts the current date range (StartDate and EndDate) into a string format suitable for display. The formatting follows the component's configured format pattern and separator settings.

GetPersistData()

Gets the properties to be maintained in the persisted state.

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

A Task that represents the asynchronous operation. The task result contains a string with the persisted data.
Remarks

This method retrieves component data that has been persisted in local storage, which is useful for maintaining state across page loads.

HidePopupAsync()

Hides the calendar popup.

Declaration
public Task HidePopupAsync()
Returns
Type Description
Task

A Task that represents the asynchronous operation.
Remarks

This method programmatically closes the DateRangePicker's calendar popup if it is currently visible.

InputHandler(ChangeEventArgs)

Handles input events when the user types in the DateRangePicker input field.

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

The ChangeEventArgs containing the input change information.
Returns
Type Description
Task

A Task representing the asynchronous operation.
Overrides
Remarks

This method processes real-time input changes, validates the input if ValidateOnInput is enabled, and updates the component's internal state. It provides immediate feedback during user input.

ShowPopupAsync()

Opens the popup to display the calendar.

Declaration
public Task ShowPopupAsync()
Returns
Type Description
Task

A Task that represents the asynchronous operation.
Remarks

This method programmatically opens the DateRangePicker's calendar popup, allowing the user to select a date range. It will not open if the component is disabled or read-only.

UpdateChildProperties(object)

Updates the child properties of the DateRangePicker component with the specified preset values.

Declaration
public void UpdateChildProperties(object presetValue)
Parameters
Type Name Description
object presetValue

An object containing the preset values to be applied to the component. Expected to be of type List<T>.
Remarks

This method converts the provided preset values into the appropriate format and updates the component's preset properties. The preset values allow users to quickly select commonly used date ranges such as "Last 7 days", "This month", etc.

Exceptions
Type Condition
InvalidCastException

Thrown when the presetValue parameter cannot be cast to the expected type.

UpdateHeaders()

Updates the header properties of the DateRangePicker popup to display the current start date, end date, and selected range information.

Declaration
public void UpdateHeaders()
Remarks

This method refreshes the popup header to show formatted start and end dates along with the number of days in the selected range. The header displays localized text for start date, end date, and range duration based on the component's locale settings. If no dates are selected, appropriate placeholder text is displayed instead.

Implements