Configuration scale

Specifies options of the range selector's scale.

Type: Object

To divide a scale, either set the dataSource property or the startValue and endValue properties. In the former case, the start and end values will be calculated based on the values provided by the data source field that is set by the dataSourceField property.

The scale's ticks are arranged automatically, based on the start and end values, so that the tick labels do not overlap each other. You can set a custom tick interval, add minor ticks and format tick labels. These and other scale options are available in the scale configuration object.

Show Example:
jQuery

In this example, the scale is divided using the values assigned to the startValue and endValue fields, and major tick interval is set to 2 using the majorTickInteval option. In addition, minor ticks are hidden, because the showMinorTicks option is set to 'false'.

<div id="rangeSelectorContainer" style="height:120px;max-width:600px;margin:0px auto"></div>
$(function () {
    $("#rangeSelectorContainer").dxRangeSelector({
        scale: {
            startValue: 0,
            endValue: 10,
            showMinorTicks: false,
            majorTickInterval: 2
        }
    });
});

endValue

Specifies the scale's end value.

Type: Number|Date
Default Value: undefined

Setting the start and end values are enough for the dxRangeSelector widget to create a scale and arrange ticks automatically. If required, you can also set the required majorTickInterval and minorTickInterval.

Show Example:
jQuery

In this example, the scale is divided using the values assigned to the startValue and endValue fields.

<div id="rangeSelectorContainer" style="height:120px;max-width:600px;margin:0px auto"></div>
$(function () {
    $("#rangeSelectorContainer").dxRangeSelector({
        scale: {
            startValue: 0,
            endValue: 100
        }
    });
});

label

Specifies common options for scale labels.

Type: Object

Scale labels represent textual values for major scale ticks. The label object exposes properties that allow you to specify custom text for scale labels and properties that allow you to change the font for text.

Show Example:
jQuery

In this example, the scale labels are formatted as 'currency' using the format option and indented from the scale by 3 pixels using the topIndent option.

<div id="rangeSelectorContainer" style="height:120px;max-width:600px;margin:0px auto"></div>
$(function () {
    $("#rangeSelectorContainer").dxRangeSelector({
        scale: {
            startValue: 0,
            endValue: 1000000,
            majorTickInterval: 200000,
            label: {
                format: 'currency',
                topIndent: 3
            }
        }
    });
});

majorTickInterval

Specifies an interval between major ticks.

Default Value: undefined
Accepted Values: number|object|'millisecond' | 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year'

Major ticks are those that are accompanied by labels that display corresponding scale values. Use this property to divide the scale by major ticks in a specified interval. If this property is not set, major ticks are automatically arranged so that labels do not overlap each other.

In the case of a numeric scale, assign a numeric value to this property. If the scale is of the date-time type, assign one of the predefined string values. To set an interval to several days, hours etc., assign an object with the corresponding field specified (days, hours or another field). Note that this object should contain only one of the fields described in this section.

NOTE: The specified tick interval can be changed internally if its value leads to label overlap. If you need to prohibit automatic tick arrangement in this situation, set the scale's useTicksAutoArrangement property to false.

Show Example:
jQuery

In this example, the majorTickInterval option is set to 'week'.

<div id="rangeSelectorContainer" style="height: 160px"></div>
$(function () {
    $("#rangeSelectorContainer").dxRangeSelector({
        scale: {
            startValue: new Date(2012, 2, 4),
            endValue: new Date(2012, 3, 10),
            majorTickInterval: 'week'
        }
    });
});

marker

Specifies options for the date-time scale's markers.

Type: Object

When a scale is of the date-time type, scale markers can be displayed. If a major tick interval is set in days, a marker will be displayed between the last day of the month and the first day of the new month. The marker will indicate the new month. The same logic for setting markers is used when a tick interval is set using other date-time units.

A marker consists of a separator and label that belongs to the separator. To set the visibility of the markers, and change their default location and appearance, use the properties of the marker configuration object.

Show Example:
jQuery

In this example, the scale markers are made visible.

<div id="rangeSelectorContainer" style="height: 160px"></div>
$(function () {
    $("#rangeSelectorContainer").dxRangeSelector({
        scale: {
            startValue: new Date(2012, 2, 5),
            endValue: new Date(2012, 4, 10),
            marker: {
                visible: true
            }
        }
    });
});

maxRange

Specifies the maximum range that can be selected.

Default Value: undefined
Accepted Values: number|object|'millisecond' | 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year'

Use this property to set the maximum range that can be selected. When trying to move a slider from the other slider further than the specified maximum range, the marker will display the last possible value that can be set and change the font color to 'red'. You can set which color to use to indicate an invalid range. For this purpose, use the invalidRangeColor property of the sliderMarker configuration object.

In case of the numeric scale, assign a numeric value to this property. If the scale is of the date-time type, assign one of the predefined string values or an object to this property. The object's properties specify the number of days, hours, etc.

You can also set a minimum range that can be selected, using the minRange property.

Show Example:
jQuery

In this example, the maxRange option is set to 'month'.

<div id="rangeSelectorContainer" style="height: 160px"></div>
$(function () {
    $("#rangeSelectorContainer").dxRangeSelector({
        behavior: {
            snapToTicks: false
        },
        scale: {
            startValue: new Date(2012, 2),
            endValue: new Date(2012, 6),
            maxRange: 'month'
        },
        selectedRange: {
            startValue: new Date(2012, 3, 1),
            endValue: new Date(2012, 4, 1)
        }
    });
});

minorTickCount

Specifies the number of minor ticks between neighboring major ticks.

Type: Number
Default Value: undefined

If you set both the minorTickCount property and the minorTickInterval property, the minorTickCount property value will be ignored.

Show Example:
jQuery

In this example, the minorTickCount option is set to 9.

<div id="rangeSelectorContainer" style="height:120px;max-width:600px;margin:0px auto"></div>
$(function () {
    $("#rangeSelectorContainer").dxRangeSelector({
        scale: {
            startValue: 0,
            endValue: 10,
            majorTickInterval: 2,
            minorTickCount: 9
        }
    });
});

minorTickInterval

Specifies an interval between minor ticks.

Default Value: undefined
Accepted Values: number|object|'millisecond' | 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year'

Major ticks are those that are accompanied by labels, which display the corresponding scale values. Minor ticks are the intermediate ticks between major ticks. Minor ticks are required when major ticks are far from each other due to label overlap. To set a custom minor tick interval, use the minorTickInterval property. If this property is not set, minor ticks are arranged automatically.

In the case of a numeric scale, assign a numeric value to this property. If the scale is of the date-time type, assign one of the predefined string values. To set an interval to several days, hours etc., assign an object with the corresponding field specified (days, hours or another field). Note that this object should contain only one of the fields described in this section.

When the snapToTicks property is set to true, sliders are docked to both major and minor ticks.

To prohibit the display of minor ticks, set the scale's showMinorTicks property to false.

To set a custom tick interval between major ticks, use the scale's majorTickInterval property.

Show Example:
jQuery

In this example, the minorTickInterval option is set to 'day'.

<div id="rangeSelectorContainer" style="height: 160px"></div>
$(function () {
    $("#rangeSelectorContainer").dxRangeSelector({
        scale: {
            startValue: new Date(2012, 2, 5),
            endValue: new Date(2012, 3, 10),
            minorTickInterval: 'day'
        }
    });
});

minRange

Specifies the minimum range that can be selected.

Default Value: undefined
Accepted Values: number|object|'millisecond' | 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year'

Use this property to set the minimum range that can be selected. When moving a slider to to a position near the other slider that is closer than the specified minimum range, the marker will display the last possible value that it can be set to, and change the font color to 'red'. You can set the color used to indicate an invalid range by using the invalidRangeColor property of the sliderMarker configuration object.

For a numeric scale, assign a numeric value to this property. If the scale is of the date-time type, assign one of the predefined string values or an object to this property. The object's properties specify the number of days, hours, etc.

You can also set the maximum range that can be selected using the maxRange property.

Show Example:
jQuery

In this example, the minRange option is set to 'week'.

<div id="rangeSelectorContainer" style="height: 160px"></div>
$(function () {
    $("#rangeSelectorContainer").dxRangeSelector({
        scale: {
            startValue: new Date(2012, 2, 4),
            endValue: new Date(2012, 3, 10),
            minRange: 'week'
        }
    });
});

placeholderHeight

Specifies the height of the space reserved for the scale in pixels.

Type: Number
Default Value: undefined

The scale's height includes the space occupied by scale labels, markers, and the space between the scale labels and markers.

You may need to set this property when you need to know the exact size of the dxRangeSelector widget elements in vertical and horizontal directions. For instance, this may be required when displaying an image in the background in a stretched mode. To get the background height, subtract the scale's placeholder size and the slider markers' placeholder height from the dxRangeSelector's height.

RangeSelectorScalePlaceholderheight ChartJS

setTicksAtUnitBeginning

Indicates whether to set ticks of a date-time scale at the beginning of each date-time interval.

Type: Boolean
Default Value: true
Accepted Values: true|false

This property is used when a date-time scale is divided. If this property is set to true, ticks are set at the beginning of date-time units (months, days, years, etc.). The following examples will help you understand the logic:

Tick Interval Start Value Ticks Generated
2 hours 11 (h) : 35 (min) : 25 (s) : 10 (ms) "13 (h) : 00 (min) : 00 (s) : 00 (ms)"; "15 (h): 00 (min) : 00 (s) : 00 (ms)"; ...
2 days 6 (d) : 11 (h) : 35 (min) "8 (d) : 00 (h) : 00 (min)"; "10 (d) : 00 (h) : 00 (min)"; ...
2 months March : 13 (d) "May : 0 (d)"; "July: 0 (d)"; ...

The values that will be generated for the scale ticks can be formatted using the format property (see Available Formats).

Show Example:
jQuery

In this example, you can change the setTicksAtUnitBeginning option using the check box below. Here, when this option is set to 'true', the scale ticks are set at the beginning of an hour. Otherwise, the ticks are generated from the start value with the major tick interval of 1 hour.

<div id="rangeSelectorContainer" style="height:150px;margin: 0px auto"></div>
<div id="checkboxContainer" style="height:20px;width:250px;margin:5px auto;font-family:'Trebuchet MS',Arial,sans-serif;font-size:14px;text-align:center">
    <input type="checkbox" id="setTicksAtUnitBeginningCheckbox" checked> setTicksAtUnitBeginning
</div>
$(function () {
    $("#rangeSelectorContainer").dxRangeSelector({
        scale: {
            startValue: new Date(2012, 2, 14, 11, 13, 25, 10),
            endValue: new Date(2012, 2, 15),
            showMinorTicks: false,
            placeholderHeight: 20,
            majorTickInterval: { hours: 1 },
            snapToTicks: true,
            useTicksAutoArrangement: false,
            setTicksAtUnitBeginning: true
        }
    });

    $("#setTicksAtUnitBeginningCheckbox").change(function () {
        var rangeSelector = $("#rangeSelectorContainer").dxRangeSelector("instance");
        rangeSelector.option({
            scale: { setTicksAtUnitBeginning: this.checked }
        });
    });
});

showCustomBoundaryTicks

Specifies whether or not to show ticks for the boundary scale values, when neither major ticks nor minor ticks are created for these values.

Type: Boolean
Default Value: true

Show Example:
jQuery

In this example, you can change the showCustomBoundaryTicks option using the check box below. Here, when this option is set to 'true', the tick at the right boundary of the scale is set. Otherwise, this tick is not generated, and you can not select the whole scale as the scale's snapToTicks option is set to 'true'.

<div id="rangeSelectorContainer" style="height:150px;margin: 0px auto"></div>
<div id="checkboxContainer" style="height:20px;width:250px;margin:5px auto;font-family:'Trebuchet MS',Arial,sans-serif;font-size:14px;text-align:center">
    <input type="checkbox" id="showCustomBoundaryTicksCheckbox" checked> showCustomBoundaryTicks
</div>
$(function () {
    $("#rangeSelectorContainer").dxRangeSelector({
        background: {
            color: 'thistle'
        },
        scale: {
            startValue: new Date(2012, 2, 14, 11, 35, 25, 10),
            endValue: new Date(2012, 2, 15),
            placeholderHeight: 20,
            majorTickInterval: { hours: 2 },
            minorTickInterval: { hours: 1 },
            setTicksAtUnitBeginning: false,
            showCustomBoundaryTicks: true
        }
    });

    $("#showCustomBoundaryTicksCheckbox").change(function () {
        var rangeSelector = $("#rangeSelectorContainer").dxRangeSelector("instance");
        rangeSelector.option({
            scale: { showCustomBoundaryTicks: this.checked }
        });
    });
});

showMinorTicks

Indicates whether to show minor ticks on the scale.

Type: Boolean
Default Value: true
Accepted Values: true|false

A scale is divided by major and minor ticks by default. Major ticks have labels that display corresponding scale values. Major ticks cannot be positioned close to each other because of label overlap. Intermediate ticks are displayed between the major ticks. The intermediate ticks are called minor ticks. When the snapToTicks property is set to true, the sliders dock to both major and minor ticks.

To divide the scale by major ticks only, set the showMinorTicks property to false.

Show Example:
jQuery

Toggle the check box below to change the showMinorTicks option.

<div id="rangeSelectorContainer" style="height:120px;max-width:800px;margin: 0px auto"></div>
<div id="checkboxContainer" style="height:20px;width:200px;margin:5px auto;font-family:'Trebuchet MS',Arial,sans-serif;font-size:14px;text-align:center">
    <input type="checkbox" id="showMinorTicksCheckbox" checked> showMinorTicks
</div>
$(function () {
    $("#rangeSelectorContainer").dxRangeSelector({
        background: {
            color: 'gainsboro'
        },
        scale: {
            startValue: new Date(2012, 2, 14),
            endValue: new Date(2012, 2, 15),
            placeholderHeight: 20,
            majorTickInterval: { hours: 2 },
            minorTickInterval: { hours: 1 },
            showMinorTicks: true
        }
    });

    $("#showMinorTicksCheckbox").change(function () {
        var rangeSelector = $("#rangeSelectorContainer").dxRangeSelector("instance");
        rangeSelector.option({
            scale: { showMinorTicks: this.checked }
        });
    });
});

startValue

Specifies the scale's start value.

Type: Number|Date
Default Value: undefined

Setting the start and end values are enough for the dxRangeSelector widget to create a scale and arrange ticks automatically. If required, you can also set the required majorTickInterval and minorTickInterval.

Show Example:
jQuery

In this example, the scale is divided using the values assigned to the startValue and endValue fields.

<div id="rangeSelectorContainer" style="height:120px;max-width:600px;margin:0px auto"></div>
$(function () {
    $("#rangeSelectorContainer").dxRangeSelector({
        scale: {
            startValue: 0,
            endValue: 100
        }
    });
});

tick

Specifies options defining the appearance of scale ticks.

Type: Object

Show Example:
jQuery

In this example, the tick appearance options are changed.

<div id="rangeSelectorContainer" style="height:120px;max-width:600px;margin:0px auto"></div>
$(function () {
    $("#rangeSelectorContainer").dxRangeSelector({
        scale: {
            startValue: 0,
            endValue: 10,
            tick: {
                color: 'white',
                opacity: 1
            }
        }
    });
});

useTicksAutoArrangement

Specifies whether to expand the current tick interval if labels overlap each other.

Type: Boolean
Default Value: true
Accepted Values: true|false

If this property is set to true, the major tick interval always changes automatically when labels overlap each other. For instance, when labels are large due to the formatting that is applied, the tick interval will increase. In addition, when you set a custom tick interval that is so small that labels overlap each other, the tick interval will increase. To prohibit the automatic arrangement of ticks, set the useTicksAutoArrangement property to false.

Show Example:
jQuery

Toggle the check box below to change the useTicksAutoArrangement option. Here, when this option is set to 'false', the scale labels overlap each other. Otherwise, the major tick interval is calculated automatically so as to prevent labels from overlapping.

<div id="rangeSelectorContainer" style="height:120px;max-width:600px;margin: 0px auto"></div>
<div id="checkboxContainer" style="height:20px;width:250px;margin:5px auto;font-family:'Trebuchet MS',Arial,sans-serif;font-size:14px;text-align:center">
    <input type="checkbox" id="useTicksAutoArrangementCheckbox" checked> useTicksAutoArrangement
</div>
$(function () {
    $("#rangeSelectorContainer").dxRangeSelector({
        background: { color: 'darkkhaki' },
        scale: {
            startValue: new Date(2012, 2, 5),
            endValue: new Date(2012, 2, 10),
            placeholderHeight: 20,
            useTicksAutoArrangement: true
        }
    });

    $("#useTicksAutoArrangementCheckbox").change(function () {
        var rangeSelector = $("#rangeSelectorContainer").dxRangeSelector("instance");
        rangeSelector.option({
            scale: { useTicksAutoArrangement: this.checked }
        });
    });
});

valueType

Specifies the type of the scale.

Type: String
Default Value: undefined
Accepted Values: 'datetime' | 'numeric' | undefined

The scale can be set by a data source assigned to the dataSource option. The type of the scale values (numeric or date-time) is determined based on the type of the values specified in the corresponding data source field. If numeric values are specified in the data source, the scale values will also be of the numeric type. The same logic is used when date-time values are specified in the data source.

In some scenarios, you may need to convert the type of the values that are specified in the data source to another type. For instance, if string values are specified in the data source, you should specify the scale's value type directly. To do this, use the scale's valueType option.

Show Example:
jQuery

In this example, the data source contains string values. To generate a scale using this data source, the scale's valueType option must be set to 'numeric'.

<div id="rangeSelectorContainer" style="height:120px;max-width:600px;margin:0px auto"></div>
$(function () {
    $("#rangeSelectorContainer").dxRangeSelector({
        dataSource: [
            { arg: '0' },
            { arg: '25' },
            { arg: '50' },
            { arg: '75' },
            { arg: '100' }
        ],
        background: { color: 'lightcoral' },
        scale: { valueType: 'numeric' }
    });
});