Range Report Parameters

• Jul 24, 2025
• 9 minutes to read

This topic describes how to create date range and time range parameters and filter a report’s data by the specified date or time values.

A date range parameter’s editor on Print Preview

The report’s data filtered by the specified date range

A time range parameter’s editor on Print Preview

Create a Range Parameter in the Report Designer

Follow the steps below to add a range parameter to a report in Visual Studio Report Designer:

1. Create a report parameter.

2. In the Add New Parameter dialog, specify parameter options:

   • Parameter type: Date and Time, Date, or Time
   • Value Source: Range Parameters

   The Start Parameter and End Parameter sections that appear allow you to configure options to create a date or time range:

   

3. You can change the Name and initial static Value for the Start Parameter and End Parameter. To specify an expression instead of a static value, click the Value option’s ellipsis button and use the Expression Editor dialog:

   

4. Reference the created range parameter. You can reference this parameter in the report’s filter string, in expressions, and in a control’s Text property. You can also bind control and data source parameters to report parameters.

   We recommend that you use the following functions with range parameters in expressions and filter strings:

   • InDateRange(Date, FromDate, ToDate) - equivalent to the FromDate <= Date && Value < Date expression.
   • InTimeRange(Time, FromTime, ToTime) - equivalent to the FromTime <= Time && Time < ToTime expression (including cases where the range spans midnight, such as 23:00-01:00).
   • OutOfTimeRange(Time, FromTime, ToTime) - equivalent to the FromTime > Time || Time => ToTime expression (including cases where the range spans midnight, such as 23:00-01:00).

   The image below filters the report’s data by the following filter string:

   InDateRange([ShippedDate], ?paramDateRange_Start, ?paramDateRange_End)

   

When you switch to the report’s Print Preview tab, the Parameters Panel displays the newly created range parameter. Click the editor to set a range. The editor type depends on the parameter type:

An editor for “Date” and “Date and Time” range parameters:

An editor for “Time” range parameters

After you submit start and end values, the report document shows filtered data. The report below shows the ShippedDate field filtered by the date range parameter:

Create a Range Parameter in Code

1. Initialize a RangeParametersSettings class instance and set up its properties.
2. Create a parameter and set its Type to a DateTime, DateOnly, or TimeOnly value.
3. Assign the created RangeParametersSettings object to the parameter’s ValueSourceSettings property.
4. Add the parameter to the report’s Parameters collection.

The following code sample creates a date range parameter in code and uses this parameter to filter the report’s data:

View Example: Create a Date Range Report Parameter

C#

using System;
using System.IO;
using DevExpress.DataAccess.ConnectionParameters;
using DevExpress.DataAccess.Sql;
using DevExpress.XtraReports.Expressions;
using DevExpress.XtraReports.Parameters;
using DevExpress.XtraReports.UI;
// ...
            // Create a date range parameter.
            var dateRangeParam = new Parameter();
            dateRangeParam.Name = "dateRange";
            dateRangeParam.Description = "Date Range:";
            dateRangeParam.Type = typeof(System.DateTime);

            // Create a RangeParametersSettings instance and set up its properties.
            var dateRangeSettings = new RangeParametersSettings();

            // Specify the start date and end date parameters.
            dateRangeSettings.StartParameter.Name = "dateRangeStart";
            dateRangeSettings.StartParameter.ExpressionBindings.Add(
                new BasicExpressionBinding("Value", "AddYears(Today(), -1)")
            );

            dateRangeSettings.EndParameter.Name = "dateRangeEnd";
            dateRangeSettings.EndParameter.ExpressionBindings.Add(
                new BasicExpressionBinding("Value", "AddYears(Today(), 0)")
            );

            // Assign the settings to the parameter's ValueSourceSettings property.
            dateRangeParam.ValueSourceSettings = dateRangeSettings;

            // Create a report instance and add the parameter to the report's Parameters collection.
            var report = new XtraReport1();
            report.Parameters.Add(dateRangeParam);

            // Use the parameter to filter the report's data.
            report.FilterString = "GetDate([UpdatedOrderDate]) Between(?dateRangeStart,?dateRangeEnd)";

VB.NET

Imports System.IO
Imports DevExpress.DataAccess.ConnectionParameters
Imports DevExpress.DataAccess.Sql
Imports DevExpress.XtraReports.Expressions
Imports DevExpress.XtraReports.Parameters
Imports DevExpress.XtraReports.UI
' ...
            ' Create a date range parameter.
            Dim dateRangeParam = New Parameter()
            dateRangeParam.Name = "dateRange"
            dateRangeParam.Description = "Date Range:"
            dateRangeParam.Type = GetType(Date)

            ' Create a RangeParametersSettings instance and set up its properties.
            Dim dateRangeSettings = New RangeParametersSettings()

            ' Specify the start date and end date parameters.
            dateRangeSettings.StartParameter.Name = "dateRangeStart"
            dateRangeSettings.StartParameter.ExpressionBindings.Add(New BasicExpressionBinding("Value", "AddYears(Today(), -1)"))
            dateRangeSettings.EndParameter.Name = "dateRangeEnd"
            dateRangeSettings.EndParameter.ExpressionBindings.Add(New BasicExpressionBinding("Value", "AddYears(Today(), 0)"))

            ' Assign the settings to the parameter's ValueSourceSettings property.
            dateRangeParam.ValueSourceSettings = dateRangeSettings

            ' Create a report instance and add the parameter to the report's Parameters collection.
            Dim report = New XtraReport1()
            report.Parameters.Add(dateRangeParam)

            ' Use the parameter to filter the report's data.
            report.FilterString = "GetDate([UpdatedOrderDate]) Between(?dateRangeStart,?dateRangeEnd)"

Customize Predefined Ranges

Web Report controls do not support DateOnly and TimeOnly range parameters. You can only create a range parameter of DateTime type.

The date and time range parameter editor allows you to select a range from a list of predefined ranges. You can remove items from the list or add a custom range.

WinForms and WPF Reporting

The set of predefined date ranges is stored in the RangeParameterEditorOptions static class and is available in all date range parameter editors when they are displayed in the Preview tab. Use the RegisterDateRange(String, Func<DateTime>, Func<DateTime>) to add a new predefined date range to the collection.

The following code sample removes all predefined date ranges and creates two new ranges:

C#

using DevExpress.XtraReports.Parameters;
using DevExpress.XtraReports.Expressions;
// ...
// Remove all predefined ranges and add two new date ranges.
RangeParameterEditorOptions.PredefinedDateRanges.Clear();
RangeParameterEditorOptions.RegisterDateRange("September", () => new DateTime(2019,9,1), () => new DateTime(2019,9,30));
RangeParameterEditorOptions.RegisterDateRange("October", () => new DateTime(2019,10,1), () => new DateTime(2019,10,31));

VB.NET

Imports DevExpress.XtraReports.Parameters
Imports DevExpress.XtraReports.Expressions
' ...
' Remove all predefined ranges and add two new date ranges.
RangeParameterEditorOptions.PredefinedDateRanges.Clear()
RangeParameterEditorOptions.RegisterDateRange("September", Function() New Date(2019,9,1), Function() New Date(2019,9,30))
RangeParameterEditorOptions.RegisterDateRange("October", Function() New Date(2019,10,1), Function() New Date(2019,10,31))

If you want to customize time ranges, use the RangeParameterEditorOptions.RegisterTimeRange methods to add a new predefined time range to the collection.

The following code adds two new time ranges to the existing collection:

C#

using DevExpress.XtraReports.Parameters;
// ...
// Uncomment the line below if you want to clear the collection before adding new time ranges:
//RangeParameterEditorOptions.PredefinedTimeRanges.Clear();
string timeRangeNightShift = "Night Shift";
if (!RangeParameterEditorOptions.PredefinedTimeRanges.ContainsKey(timeRangeNightShift)) {
    RangeParameterEditorOptions.RegisterTimeRange(timeRangeNightShift,() => new TimeOnly(23,0),() => new TimeOnly(5,0),SvgImage.FromFile("time.svg"));
}
string timeRangeLastTwoHours = "Last Two Hours";
if (!RangeParameterEditorOptions.PredefinedTimeRanges.ContainsKey(timeRangeLastTwoHours)) {
    TimeOnly previousHour = TimeOnly.FromDateTime(DateTime.Now.AddHours(-2));
    TimeOnly currentHour = TimeOnly.FromDateTime(DateTime.Now.AddHours(0));
    RangeParameterEditorOptions.RegisterTimeRange(timeRangeLastTwoHours, () => previousHour,() => currentHour);
}

VB.NET

Imports DevExpress.XtraReports.Parameters
Imports DevExpress.XtraReports.Expressions
' ...
' Uncomment the line below if you want to clear the collection before adding new time ranges:
' RangeParameterEditorOptions.PredefinedTimeRanges.Clear()
Dim timeRangeNightShift As String = "Night Shift"
If Not RangeParameterEditorOptions.PredefinedTimeRanges.ContainsKey(timeRangeNightShift) Then
    RangeParameterEditorOptions.RegisterTimeRange(timeRangeNightShift, Function() New TimeOnly(23, 0), Function() New TimeOnly(5, 0), SvgImage.FromFile("time.svg"))
End If

Dim timeRangeLastTwoHours As String = "Last Two Hours"
If Not RangeParameterEditorOptions.PredefinedTimeRanges.ContainsKey(timeRangeLastTwoHours) Then
    Dim previousHour As TimeOnly = TimeOnly.FromDateTime(DateTime.Now.AddHours(-2))
    Dim currentHour As TimeOnly = TimeOnly.FromDateTime(DateTime.Now.AddHours(0))
    RangeParameterEditorOptions.RegisterTimeRange(timeRangeLastTwoHours, Function() previousHour, Function() currentHour)
End If

Web Reporting

Warning

• Web Report controls do not support DateOnly and TimeOnly range parameters. You can only create a range parameter of DateTime type.

• The Native Report Viewer for Blazor does not support predefined date ranges for date range report parameters.

Predefined date ranges are stored in the client-side collection of the Document Viewer widgets. The set of predefined date ranges is available in all date range parameter editors when they are displayed in the Preview tab.

The following code removes built-in predefined ranges and adds two custom predefined ranges.

ASP.NET Web Forms

<script type="text/javascript" id="script">
    function CustomizePredefinedRanges(s, e) {
        DevExpress.Reporting.Viewer.Widgets.predefinedDateRanges.splice(0,
            DevExpress.Reporting.Viewer.Widgets.predefinedDateRanges.length);

        DevExpress.Reporting.Viewer.Widgets.predefinedDateRanges.push({
            displayName: 'September',
            range: () => [
                new Date(2023, 8, 1),
                new Date(2023, 8, 30)
            ]
        })
        DevExpress.Reporting.Viewer.Widgets.predefinedDateRanges.push({
            displayName: 'October',
            range: () => [
                new Date(2023, 9, 1),
                new Date(2023, 9, 31)
            ]
        })
    }
</script>

<dx:ASPxWebDocumentViewer ClientInstanceName="WebDocumentViewer1" ID="ASPxWebDocumentViewer1" runat="server">
    <ClientSideEvents BeforeRender ="CustomizePredefinedRanges" />
</dx:ASPxWebDocumentViewer>

ASP.NET MVC

<script type="text/javascript" id="script">
    function CustomizePredefinedRanges(s, e) {
        DevExpress.Reporting.Viewer.Widgets.predefinedDateRanges.splice(0,
            DevExpress.Reporting.Viewer.Widgets.predefinedDateRanges.length);

        DevExpress.Reporting.Viewer.Widgets.predefinedDateRanges.push({
            displayName: 'September',
            range: () => [
                new Date(2023, 8, 1),
                new Date(2023, 8, 30)
            ]
        })
        DevExpress.Reporting.Viewer.Widgets.predefinedDateRanges.push({
            displayName: 'October',
            range: () => [
                new Date(2023, 9, 1),
                new Date(2023, 9, 31)
            ]
        })
    }
</script>

@Html.DevExpress().WebDocumentViewer(settings =>
{
    settings.Name = "WebDocumentViewer1";
    settings.ClientSideEvents.BeforeRender = "CustomizePredefinedRanges";
}).Bind("XtraReport1").GetHtml()

ASP.NET Core

<script type="text/javascript" id="script"> 
    function CustomizePredefinedRanges(s, e) {
        DevExpress.Reporting.Viewer.Widgets.predefinedDateRanges.splice(0,
            DevExpress.Reporting.Viewer.Widgets.predefinedDateRanges.length);

        DevExpress.Reporting.Viewer.Widgets.predefinedDateRanges.push({
            displayName: 'September',
            range: () => [
                new Date(2023, 8, 1),
                new Date(2023, 8, 30)
            ]
        })
        DevExpress.Reporting.Viewer.Widgets.predefinedDateRanges.push({
            displayName: 'October',
            range: () => [
                new Date(2023, 9, 1),
                new Date(2023, 9, 31)
            ]
        })
    }
</script>

@{
    var viewerRender = Html.DevExpress().WebDocumentViewer("DocumentViewer")
        .Height("1000px")
        .ClientSideEvents(configure =>
        {
            configure.BeforeRender("CustomizePredefinedRanges");
        })
        .Bind("XtraReport1");
    @viewerRender.RenderHtml()
}

Angular

 

report-viewer.html

<div>
    <dx-report-viewer [reportUrl]="reportUrl" height="800px">
        <dxrv-request-options [invokeAction]="invokeAction" [host]="hostUrl">
        </dxrv-request-options>
        <dxrv-callbacks (BeforeRender)="CustomizePredefinedRanges($event)">
        </dxrv-callbacks>
    </dx-report-viewer>
</div>

 

report-viewer.ts

import { predefinedDateRanges } from 'devexpress-reporting/dx-webdocumentviewer'


export class ReportViewerComponent {
    // ...

    CustomizePredefinedRanges(event) {
        predefinedDateRanges.splice(0,
            predefinedDateRanges.length);

        predefinedDateRanges.push({
            displayName: 'September',
            range: () => [
                new Date(2023, 8, 1),
                new Date(2023, 8, 30)
            ]
        })
        predefinedDateRanges.push({
            displayName: 'October',
            range: () => [
                new Date(2023, 9, 1),
                new Date(2023, 9, 31)
            ]
        })
    }
    // ...
}

React

'use client';
import React from 'react';
import ReportViewer, { RequestOptions, Callbacks } from 'devexpress-reporting-react/dx-report-viewer';
import { predefinedDateRanges } from 'devexpress-reporting/dx-webdocumentviewer'


function App() {
    const onBeforeRender = ({ args }: { args: any }) => {
        console.log("onBeforeRender");
        predefinedDateRanges.splice(0,
            predefinedDateRanges.length);

        predefinedDateRanges.push({
            displayName: 'September',
            range: () => [
                new Date(2024, 8, 1),
                new Date(2024, 8, 30)
            ]
        })
        predefinedDateRanges.push({
            displayName: 'October',
            range: () => [
                new Date(2024, 9, 1),
                new Date(2024, 9, 31)
            ]
        })
    };

    return (
        <ReportViewer reportUrl="TestExportReport">
            <RequestOptions host="http://localhost:5000/" invokeAction="DXXRDV" />
            <Callbacks BeforeRender={onBeforeRender} />
        </ReportViewer>
    )
}

export default App;

Vue

import { predefinedDateRanges } from 'devexpress-reporting/dx-webdocumentviewer'
import ko from "knockout";


var componentData = {
    name: "WebDocumentViewer",
    mounted() {
    // ...
    var callbacks = {  
          BeforeRender: function(){
                predefinedDateRanges.splice(0,
                    predefinedDateRanges.length);

                predefinedDateRanges.push({
                    displayName: 'September',
                    range: () => [
                        new Date(2023, 8, 1),
                        new Date(2023, 8, 30)
                    ]
                })
                predefinedDateRanges.push({
                    displayName: 'October',
                    range: () => [
                        new Date(2023, 9, 1),
                        new Date(2023, 9, 31)
                    ]
                })
                }
            };  
        ko.applyBindings({
      // ..
            callbacks: callbacks
        }, this.$refs.viewer);
    },
  // ...
};
export default componentData;

Blazor- Document Viewer

 

index.html

<script type="text/javascript">
    window.viewerCustomization = {
        onBeforeRender: function (s, e) {
            DevExpress.Reporting.Viewer.Widgets.predefinedDateRanges.splice(0,
                DevExpress.Reporting.Viewer.Widgets.predefinedDateRanges.length);

            DevExpress.Reporting.Viewer.Widgets.predefinedDateRanges.push({
                displayName: 'September',
                range: () => [
                    new Date(2023, 8, 1),
                    new Date(2023, 8, 30)
                ]
            })
            DevExpress.Reporting.Viewer.Widgets.predefinedDateRanges.push({
                displayName: 'October',
                range: () => [
                    new Date(2023, 9, 1),
                    new Date(2023, 9, 31)
                ]
            })

        }
    };
</script>

 

DocumentViewer.razor

@page "/documentviewer"

<DxDocumentViewer ReportName="XtraReport1" Height="calc(100vh - 130px)" Width="100%">
    <DxDocumentViewerTabPanelSettings Width="340" />
    <DxDocumentViewerCallbacks BeforeRender="designerCustomization.onBeforeRender" />
</DxDocumentViewer>

Limitations

• Web Report controls do not support DateOnly and TimeOnly range parameters. You can only create a range parameter of DateTime type.

• The Native Report Viewer for Blazor does not support predefined date ranges.