RangeSelector Elements

The image below is the dxRangeSelector element map that can be helpful to you as you begin learning about dxRangeSelector capabilities. Hover over the image and you will learn how different dxRangeSelector elements are called. Click an element to navigate to a topic with more details.

Slider Marker Slider Marker Scale Marker Scale Marker Scale Label Scale Label Scale Label Scale Label Scale Label Scale Label Scale Label Scale Label Major Scale Tick Major Scale Tick Major Scale Tick Major Scale Tick Major Scale Tick Major Scale Tick Major Scale Tick Minor Scale Tick Minor Scale Tick Minor Scale Tick Minor Scale Tick Minor Scale Tick Minor Scale Tick Minor Scale Tick Minor Scale Tick Slider Handle Slider Handle Shutter Shutter Background Background Chart

Scale

The range selector's scale indicates values that lie within scale boundaries. When a range selector is created using a data source, the scale boundaries are being defined automatically. However, you can define them explicitly using the startValue and endValue options.

This section describes the elements that the range selector's scale consists of. To configure these elements, use the options of the scale object.

Major Scale Ticks

The range selector's scale is divided using two types of ticks: major and minor. Major ticks are accompanied with scale labels, while minor ticks are not.

ChartJS RangeSelector

The appearance of the major ticks can be customized using the options of the tick object.

JavaScript
var rangeSelectorOptions = {
    scale: {
    // ...
        tick: {
            color: 'white',
            opacity: 0.9,
            width: 2
        }
    }
};

Major ticks can be arranged on the scale in several different ways. By default, major ticks arrange automatically with an interval that prevents scale labels from overlapping. If you are not satisfied with major ticks arranged like that, you can specify a custom interval for the ticks using the tickInterval option.

NOTE: When you are specifying a custom tick interval, make sure the useTicksAutoArrangement option is set to false. If it is not, the specified tick interval may be ignored, but only if it leads to label overlap.

When you use a date-time scale, and its start value does not match the beginning of any date-time unit (hour, day, month, etc.), major ticks arrange differently depending on the value of the setTicksAtUnitBeginning option. The following table illustrates how this option impacts tick arrangement.

Scale Start Value Major Tick Interval Major Ticks are Generated at
setTicksAtUnitBeginning: true setTicksAtUnitBeginning: false
11h13min 1 hour 11h13min; 12h00min; 13h00min; ... 11h13min; 12h13min; 13h13min; ...
14d11h13min 2 days 14d11h13min; 16d00h00min; 18d00h00min; ... 14d11h13min; 16d11h13min; 18d11h13min; ...
1995y11m18d 4 months 1995y11m18d; 1996y03m01d; 1996y07m01d; ... 1995y11m18d; 1996y03m18d; 1996y07m18d; ...

Minor Scale Ticks

Minor scale ticks are being placed between major ticks. They designate subsidiary tick values on a scale.

ChartJS RangeSelector

Unlike major ticks, minor ticks are not accompanied with scale labels. However, their appearance can be customized using the options of the tick object, like the appearance of major ticks.

JavaScript
var rangeSelectorOptions = {
    scale: {
    // ...
        tick: {
            color: 'white',
            opacity: 0.9,
            width: 2
        }
    }
};

By default, minor ticks arrange on the scale automatically, but you can specify a custom interval for them. To do this, use the minorTickInterval option. Besides, minor ticks can be arranged using the minorTickCount option. This option specifies the number of minor ticks between two major ticks.

NOTE: When both the minorTickInterval and minorTickCount options are specified, minor ticks will be arranged according to the interval, not the count.

If you do not need to display minor ticks at all, set the showMinorTicks option to false.

In addition, you can specify whether or not to place a tick at the end of the scale in case when, according to the settings of the tick arrangement, no ticks should be placed there. To do this, use the showCustomBoundaryTicks option.

Scale Labels

Each major scale tick is accompanied with a scale label. This label displays the value of the tick.

ChartJS RangeSelector

To customize scale labels, use the options of the label configuration object.

JavaScript
var rangeSelectorOptions = {
    scale: {
    // ...
        label: {
            // ...
        }
    }
};

A brief overview of the scale label options is given below.

  • Visibility
    By default, scale labels are visible. To hide them, set the visible option to false.

  • Text Customization
    You can specify a format and precision for the value displayed by a label. Moreover, you are not limited to displaying the tick value only - you can customize the label's text per your requirements using the customizeText option.

  • Appearance
    The font style used for displaying the label text can be varied using options of the font configuration object. In addition, scale labels can be indented from the scale itself using the topIndent option.

Scale Markers

When you use the scale of the date-time type, scale markers can be displayed. A scale marker consists of a separator and a text representing additional information on a scale tick. For example, when scale labels display tick values specified in months, a scale marker is placed at the first month of a year and displays the value of this year.

ChartJS RangeSelector

To customize scale markers, use the options of the marker configuration object.

JavaScript
var rangeSelectorOptions = {
    scale: {
    // ...
        marker: {
            // ...
        }
    }
};

A brief overview of scale marker options is given below.

  • Visibility
    By default, scale markers are visible. To hide them, set the visible option to false.

  • Text Customization
    You can specify a format for the value displayed by a marker. Moreover, you are not limited to displaying this value only - you can customize the marker's text per your requirements using the customizeText option.

  • Layout
    There are several options specifying the indents of marker elements. Use the topIndent option to set the distance between scale markers and scale labels. Also, the marker text can be indented from the separator using the textTopIndent and textLeftIndent options. In addition, you can set the height of marker separators. Use the separatorHeight option to do this.

Sliders

In the dxRangeSelector widget, sliders perform as the elements of control. By dragging them, you can select a range.

ChartJS RangeSelector

There are two sliders on a range selector: left and right. Each slider consists of a handle and a marker, whose appearance can be specified using the sliderHandle and sliderMarker configuration objects, respectively. The sliderHandle object does not have many options. You can change the color, opacity and width of slider handles using the corresponding fields of this object. In contrast, the sliderMarker object has more options. A brief overview of them is given below.

  • Visibility
    Slider markers are displayed by default. To hide them, assign false to the visible option.

  • Text Customization
    You can specify a format for the values displayed by slider markers. If these values have one of the numeric formats ('fixedPoint', 'currency', 'percent', etc.), you can set a precision for them. Moreover, you are not limited to displaying only the values - you can customize the marker's text per your requirements using the customizeText option.

  • Appearance
    The font style used for displaying marker text can be varied using options of the font configuration object. Also, you can change the distance between marker borders and its text using the padding option. In addition, you can specify a color for slider handles for times when the selected range falls out of the valid range specified by the minRange and maxRange options. For this purpose, use the invalidRangeColor option.

  • Layout
    When you must specify the exact height that a range selector should occupy, specify the placeholderHeight and/or indent options.

Background

This section describes customizations that can be applied to the dxRangeSelector background. Although these customizations are very easy to configure, they drastically change the appearance of the widget. See the following subtopics to discover how to adjust the widget's background to your own needs.

Displaying an Image

You can display an image in the background of dxRangeSelector. To do this, use the options within the background | image object. Specify the URL of the required image using the url option. Then, choose where to place this image on your range selector using the location option.

JavaScript
var rangeSelectorOptions = {
    // ...
    background: {
        image: {
            url: '/Content/images/doc/15_2/ChartJS/flight.png',
            location: 'center'
        }
    }
};

In case your image does not cover the whole range selector's background, set up a color for the uncovered area using the background | color option.

View Demo

Displaying a Chart

To display a chart in the dxRangeSelector background, provide data for it using the dataSource option. Next, specify the fields to be used as the argument and value fields. To do this, use the argumentField and valueField options within the series object. In case you have several chart series, their common settings can be specified within the commonSeriesSettings object.

JavaScript
var rangeSelectorOptions = {
    dataSource: [
        { x: 10, y1: 0, y2: 10 },
        { x: 15, y1: 6, y2: 12 },
        { x: 20, y1: 8, y2: 15 },
        { x: 30, y1: 10, y2: 10 },
        { x: 50, y1: 16, y2: 5 }
    ],
    chart: {
        commonSeriesSettings: {
            argumentField: 'x'
        },
        series: [
            { valueField: 'y1' },
            { valueField: 'y2' }
        ]
    }
};

Additionally, you can set up a color for the range selector's background using the background | color option. In this case, a chart will be displayed on the background that will be painted in the specified color.

Besides displaying a chart in the background, the dxRangeSelector widget can be bound to the dxChart widget in order to perform zooming and scrolling on the chart. Refer to the End-User Interaction topic to learn more about these advanced features.

View Demo

Setting Up a Color

To set a required color for the background, use the color option within the background configuration object.

JavaScript
var rangeSelectorOptions = {
    // ...
    background: {
        color: '#FFE4B5'
    }
};

Shutters

Shutters cover unselected ranges on a range selector.

ChartJS RangeSelector

The appearance of shutters is being specified using the shutter configuration object. Within this object you can set a color and opacity for shutters.

JavaScript
var rangeSelectorOptions = {
    // ...
    shutter: {
        color: 'powderblue',
        opacity: 0.7
    }
};

When a color for shutters is not specified, the shutters are painted in the color of the container.

NOTE: Shutters are available only when the background is set.