Gauge Elements

Topics in this section describe various elements of the dxCircularGauge, dxLinearGauge and dxBarGauge widgets. Each topic gives a detailed overview of the element's purpose and ways of configuring. Below there are the element maps of each widget. Hover over a map and you will discover how different gauge elements are called. Click an element to navigate to the topic with details on this element.

Title Subtitle Scale Label Scale Label Scale Label Scale Label Scale Label Scale Label Scale Label Scale Label Scale Label Scale Label Scale Label Scale Label Scale Label Scale Label Scale Label Scale Label Scale Label Scale Label Scale Label Tooltip Major Scale Tick Major Scale Tick Major Scale Tick Major Scale Tick Major Scale Tick Major Scale Tick Major Scale Tick Major Scale Tick Major Scale Tick Major Scale Tick Major Scale Tick Major Scale Tick Major Scale Tick Major Scale Tick Major Scale Tick Major Scale Tick Subvalue Indicator Subvalue Indicator Subvalue Indicator Value Indicator Range Container Range Container

Title Subtitle Label Label Label Label Tooltip Bar Bar Bar Bar

Title Subtitle Scale Label Scale Label Scale Label Scale Label Scale Label Scale Label Scale Label Scale Label Scale Label Scale Label Scale Label Tooltip Major Scale Tick Major Scale Tick Major Scale Tick Major Scale Tick Major Scale Tick Major Scale Tick Major Scale Tick Major Scale Tick Major Scale Tick Range Container Subvalue Indicator Subvalue Indicator Subvalue Indicator Value Indicator

dxCircularGauge and dxLinearGauge Elements

This section describes elements that are specific to the dxCircularGauge and dxLinearGauge widgets. In addition, there are several elements that are common for all the gauges. These elements are described in the Common Gauge Elements section.

Value Indicator

A value indicator is a pointer that designates the main value on a gauge. There is a set of predefined value indicator types for the dxCircularGauge and dxLinearGauge widgets.

dxCircularGauge

View Demo

dxLinearGauge

View Demo

In order to customize the appearance of a value indicator, use the valueIndicator configuration object. Set its type option and then the required type-specific options. The type specific options are listed within the widget's Indicator Types reference section.

JavaScript
var gaugeOptions = {
    valueIndicator: {
        type: 'rangeBar',
        //specify type-specific options
    }
};

Subvalue Indicators

Subvalue indicators are pointers that indicate extra values on a gauge. These extra values are called "subvalues". There is a set of predefined subvalue indicator types for the dxCircularGauge and dxLinearGauge widgets.

dxCircularGauge

View Demo

dxLinearGauge

View Demo

In order to customize the appearance of the subvalue indicators, use the subvalueIndicator configuration object. Set its type option and then the required type-specific options. The type specific options are listed within the widget's Indicator Types reference section.

JavaScript
var gaugeOptions = {
    subvalueIndicator: {
        type: 'textCloud',
        //specify type-specific options
    }
};

NOTE: Although a gauge can indicate several subvalues at once, you cannot customize a particular subvalue indicator. The options specified by the subvalueIndicator object apply to all subvalue indicators.

Scale Ticks

Values and subvalues are indicated on a gauge scale that is divided by scale ticks. These ticks can be major or minor.

ChartJS GaugesScaleTicks

To configure major and minor scale ticks, use the scale | majorTick and scale | minorTick configuration objects, respectively.

JavaScript
var gaugeOptions = {
    scale: {
        majorTick: {
            // ...
        },
        minorTick: {
            // ...
        }
    }
};

Major ticks are visible by default. To display minor ticks, you need to set the minorTick | visible option to true. You can change the visibility of the major ticks using the same option within the majorTick configuration object.

By default, scale ticks are generated automatically. Since ticks are accompanied by scale labels, an optimum tick interval is selected so that the labels do not overlap each other. To turn off automatic tick arrangement, set the useTicksAutoArrangement option to false.

If you are not satisfied with the automatically generated ticks, you can specify a custom interval for major and minor ticks. To do this, use the tickInterval option of the majorTick or minorTick objects, respectively.

NOTE: To arrange ticks precisely with a specified tick interval, set the useTicksAutoArrangement option to false. Otherwise, the specified tick interval will be ignored, but only if arranging ticks with this interval leads to label overlap.

JavaScript
var gaugeOptions = {
    scale: {
        majorTick: {
            tickInterval: 10,
            useTicksAutoArrangement: false
        },
        minorTick: {
            tickInterval: 2
        }
    }
};

If neither automatically generated ticks nor ticks with a custom interval fit your requirements, you can place major and minor ticks at specific scale values. Assign an array of required values to the customTickValues option of the majorTick or minorTick object, respectively.

NOTE: In a common case, when you use custom ticks, they mix with automatically generated ones, and the scale appears cluttered. To prevent this, hide all calculated ticks by setting the majorTick | showCalculatedTicks or minorTick | showCalculatedTicks option to false.

JavaScript
var gaugeOptions = {
    scale: {
        majorTick: {
            showCalculatedTicks: false,
            customTickValues: [4, 42, 85, 36, 14]
        },
        minorTick: {
            showCalculatedTicks: false,
            customTickValues: [24, 61, 9, 12, 95]
        }
    }
};

In addition, you can specify the color, length and width of major and minor ticks using the corresponding options of the majorTick or minorTick configuration objects.

Scale Labels

Major scale ticks can be accompanied by scale labels. These labels display scale values. Scale labels are designed to make data represented by a gauge more comprehensible.

ChartJS GaugesScaleLabels

To configure scale labels, use the options within the scale | label object.

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

These options are briefly described below.

  • Visibility
    You can show/hide scale labels using the visible option.

  • Text Customization
    You can specify a format and precision for the value displayed by a label. Moreover, you are not limited to displaying scale values 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 their ticks using the indentFromTick option.

Range Container

For the purpose of more intelligible data visualization, scale values can be combined into ranges, each of which can be colored differently. For example, you can indicate the ranges of warm and cold temperatures.

ChartJS RangeContainer

To specify the ranges, assign an array of objects defining these ranges to the ranges option of the rangeContainer configuration object.

JavaScript
var gaugeOptions = {
    rangeContainer: {
        ranges: [
            { startValue: -50, endValue: -30, color: 'midnightblue' },
            { startValue: -30, endValue: -15, color: 'blue' }
            // ...
        ]
    }
};

As you can see from the code above, each range is defined by its start and end values and, additionally, a color.

Besides the options that apply to ranges, there are several options that apply to the range container itself. They can be configured within the rangeContainer object. A brief overview of them is explained below.

  • Appearance
    If you do not need to specify a particular color for each range, you can apply one of the predefined palettes using the palette option. However, when a specific color is assigned to a range, it overrides the color specified by the palette. If a range container does not have any ranges, or the ranges do not cover the whole range container, you can specify a color for the range container itself. For this purpose, use the backgroundColor option. In addition, you can change the width of the range container or its offset from a scale using the corresponding options.

  • Geometry
    You can specify how to locate the range container relatively to the scale. To do this, specify the orientation option of the dxCircularGauge widget or the horizontalOrientation/verticalOrientation options of the dxLinearGauge widget.

dxBarGauge Elements

This section describes elements that are specific to the dxBarGauge widget. In addition, there are several elements that are common for all the gauges. These elements are described in the Common Gauge Elements section.

Bars

Gauge bars display values on a bar gauge. Each bar is located on a separate circular track and indicates one value.

ChartJS GaugeBars

There are several options for customizing the bar's appearance and arrangement. A brief overview of them is explained below.

  • Color
    Although you cannot color each bar explicitly, you can use a palette instead. A number of predefined palettes are available for this purpose. In addition, you can specify your own palette by assigning an array of colors to the palette option. The background color can be specified in addition to the bar color. The bar's background is the remaining segment of the bar's track. It can be colored using the backgroundColor option.

  • Geometry and Arrangement
    You can change the shape of a gauge using the geometry option. The radius of the gauge can also be changed. Use the relativeInnerRadius option to do this. In addition, you can separate the distance between gauge bars using the barSpacing option.

Labels

Each gauge bar can be accompanied by a label that displays the value indicated by this bar. A bar label is colored the same as the corresponding bar. Labels make a gauge more representative and easier to understand.

ChartJS GaugeBarLabels

Bar labels can be tuned using label configuration object options.

JavaScript
var barGaugeOptions = {
    label: {
        // ...
    }
};

These options are briefly described below.

  • Visibility
    Bar labels are displayed by default. To hide them, assign false to the visible option or directly to the label field.

  • Text Customization
    You can specify a format and precision for the value displayed by a label. Moreover, you are not limited to displaying the value of a bar 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 font configuration object options. Also, the width and color of the label's connector can be changed using the connectorColor and connectorWidth options respectively. In addition, bar labels can be indented from the upper bar using the indent option.

View Demo

Common Gauge Elements

This section describes elements that are common for the dxCircularGauge, dxLinearGauge and dxBarGauge widgets.

Tooltips

A tooltip is a small pop-up rectangle that displays information on a hovered value or subvalue indicator in dxCircularGauge and dxLinearGauge, or a hovered bar in dxBarGauge. By default, a tooltip shows the value indicated by the hovered element. However, it is possible to display other information in a tooltip. You can customize the text of a tooltip and its appearance in the way you require.

ChartJS GaugesTooltips

Tooltips are not enabled by default. To enable them, set the enabled option of the tooltip object to true.

JavaScript
var gaugeOptions = {
    tooltip: {
        enabled: true
    }
};

You can change default tooltip settings by defining the options within the tooltip configuration object. Some of these options are categorized and listed below.

  • Text Customization and Formatting
    By default, a tooltip displays the value of a hovered widget element without formatting. Set the format and precision options to format this value. When text customization is required, assign a function specifying the text to be shown to the customizeTooltip option. Learn more in the Data Formatting topic.

  • Font Settings
    To customize the appearance of the tooltip text, define the font options within the font configuration object.

Show Example:
jQuery
<div style="text-align:center">
    <div id="circularGaugeContainer" style="height:330px; max-width:350px; display:inline-block; margin: 0 auto"></div>
    <div id="barGaugeContainer" style="height:330px; max-width:450px; display:inline-block; margin: 0 auto"></div>
    <div id="linearGaugeContainer" style="height:120px; max-width:330px; display:block; margin: 0 auto"></div>
</div>
$(function () {
    $('#circularGaugeContainer').dxCircularGauge({
        startValue: 0,
        endValue: 100,
        value: 34,
        subvalues: [30.3, 34.8, 7],
        tooltip: { enabled: true }
    });
});

$(function () {
    $('#barGaugeContainer').dxBarGauge({
        startValue: -50,
        endValue: 50,
        values: [30.3, 34.8, -8, 7],
        tooltip: { enabled: true }
    });
});

$(function () {
    $('#linearGaugeContainer').dxLinearGauge({
        startValue: 0,
        endValue: 100,
        value: 30.3,
        subvalues: [30.3, 34.8, 7],
        tooltip: { enabled: true }
    });
});

Title and Subtitle

Gauge widgets can be displayed with a title and a subtitle. These elements usually contain general explanations about the data represented by the gauge. You can, however, place any kind of information in the gauge title and subtitle.

ChartJS GaugesTitleSubtitle

To specify a gauge title and subtitle, use the title and subtitle options, respectively. If you do not need to change any title or subtitle options except text, assign the required text directly to the title or subtitle option, as demonstrated in the code below.

JavaScript
var gaugeOptions = {
    title: 'Gauge Title',
    subtitle: 'Gauge Subtitle'
};

If you need to alter more options, set the required text to the text field within the title or subtitle configuration object. Then, specify the required options using the same configuration object.

JavaScript
var gaugeOptions = {
    title: {
        text: 'Gauge Title',
        font: {
            size: 30,
            weight: 400
        }
    },
    subtitle: {
        text: 'Gauge Subtitle',
        font: {
            size: 15,
            weight: 100
        }
    }
};

Several title options that can be set within the title and subtitle objects are categorized and listed below.

  • Location
    You can place a title on any side of your gauge. For this purpose, use the position option. Note that if this option is specified, a subtitle will be displayed at the same position as the title.

  • Font Settings
    To customize the appearance of the text, define the font options within the font configuration object.