Box
Map

JavaScript/jQuery PolarChart - valueAxis

Specifies value axis properties for the PolarChart UI component.

Type:

ValueAxis

For charting, the polar coordinate system is used to determine each point uniquely on a plane through two numbers, the argument and the value of the point. A circular and straight lines (the axis of arguments and the axis of values) are specified to define the coordinates. To define the argument axis, use the argumentAxis configuration object. To define the value axis, use the valueAxis configuration object.

To set the properties of all axes to a common value, use the commonAxisSettings configuration object. It exposes properties that can be specified for all axes simultaneously. Note that the value specified for an axis individually (in the argumentAxis or valueAxis object) overrides the value that specified in the commonAxisSettings object.

allowDecimals

Specifies whether to allow decimal values on the axis. When false, the axis contains integer values only.

Type:

Boolean

Default Value: undefined

axisDivisionFactor

Specifies a coefficient for dividing the value axis.

Type:

Number

Default Value: 30

The value axis is divided automatically by default. If you need to make the axis tick interval larger or smaller, use the axisDivisionFactor property. This property value is a coefficient used internally to calculate the distance between axis labels. This allows you to set axis division without knowledge of the actual axis values.

NOTE
This property is used for continuous and logarithmic argument axes only.

categories

Specifies the order of categories on an axis of the "discrete" type.

Type:

Array<Number | String | Date>

Values of the string type on discrete axes maintain the order of objects in the data source. Values of the number and date types are sorted in ascending order regardless of their order within the data source. Specify the categories array to set the required order of values. In the following example, the values are sorted alphabetically:

jQuery
JavaScript
$(function() {
    $('#polarChartContainer').dxPolarChart({
        // ...
        dataSource: dataSource,
        valueAxis: {
            categories: continentNames,
            valueField: 'continent'
        }
    });

    const dataSource = [
        { continent: 'Asia', area: 43820000 },
        { continent: 'Africa', area: 30370000 },
        { continent: 'North America', area: 24490000 },
        { continent: 'South America', area: 17840000 },
        { continent: 'Antarctica', area: 13720000 },
        { continent: 'Europe', area: 10180000 },
        { continent: 'Australia', area: 9008500 }
    ];

    const continentNames = [
        'Africa', 
        'Antarctica', 
        'Asia', 
        'Australia',
        'Europe',
        'North America',
        'South America'
    ];
});
Angular
app.component.html
app.component.ts
app.module.ts
<dx-polar-chart ...
    [dataSource]="dataSource">
    <dxo-value-axis
        [categories]="continentNames"
        valueField="continent">
    </dxo-value-axis>
</dx-polar-chart>
import { Component } from '@angular/core';
@Component({
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: ['./app.component.css']
})
export class AppComponent {
    dataSource = [
        { continent: 'Asia', area: 43820000 },
        { continent: 'Africa', area: 30370000 },
        { continent: 'North America', area: 24490000 },
        { continent: 'South America', area: 17840000 },
        { continent: 'Antarctica', area: 13720000 },
        { continent: 'Europe', area: 10180000 },
        { continent: 'Australia', area: 9008500 }
    ];

    continentNames = [
        'Africa', 
        'Antarctica', 
        'Asia', 
        'Australia',
        'Europe',
        'North America',
        'South America'
    ];
}
import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { AppComponent } from './app.component';

import { DxPolarChartModule } from 'devextreme-angular';

@NgModule({
    declarations: [
        AppComponent
    ],
    imports: [
        BrowserModule,
        DxPolarChartModule
    ],
    providers: [ ],
    bootstrap: [AppComponent]
})
export class AppModule { }
Vue
App.vue
<template>
    <DxPolarChart ... 
        :data-source="dataSource">
        <DxValueAxis 
            :categories="continentNames"
            value-field="continent" 
        />
    </DxPolarChart>
</template>

<script>
import DxPolarChart, {
    DxValueAxis
} from 'devextreme-vue/polar-chart'; 

export default {
    components: {
        DxPolarChart,
        DxValueAxis
    },
    data() {
        return {
            dataSource: [
                { continent: 'Asia', area: 43820000 },
                { continent: 'Africa', area: 30370000 },
                { continent: 'North America', area: 24490000 },
                { continent: 'South America', area: 17840000 },
                { continent: 'Antarctica', area: 13720000 },
                { continent: 'Europe', area: 10180000 },
                { continent: 'Australia', area: 9008500 }
            ],

            continentNames: [
                'Africa', 
                'Antarctica', 
                'Asia', 
                'Australia',
                'Europe',
                'North America',
                'South America'
            ]
        };
    }
}
</script>
React
App.js
import React from 'react';

import PolarChart, {
    ValueAxis
} from 'devextreme-react/polar-chart';

const dataSource = [
    { continent: 'Asia', area: 43820000 },
    { continent: 'Africa', area: 30370000 },
    { continent: 'North America', area: 24490000 },
    { continent: 'South America', area: 17840000 },
    { continent: 'Antarctica', area: 13720000 },
    { continent: 'Europe', area: 10180000 },
    { continent: 'Australia', area: 9008500 }
];

const continentNames = [
    'Africa', 
    'Antarctica', 
    'Asia', 
    'Australia',
    'Europe',
    'North America',
    'South America'
];

class App extends React.Component {
    render() {
        return (
            <PolarChart ... 
                dataSource={dataSource}>
                <ValueAxis
                    categories={continentNames}
                    valueField="continent"
                />
            </PolarChart>
        );
    }
}

export default App;     

color

Specifies the color of the line that represents an axis.

Type:

String

Default Value: '#767676'

This property supports the following colors:

constantLines[]

Defines an array of the value axis constant lines.

Cannot be used in themes.

A constant line is a straight line that can be used to display, for example, an asymptote of a graph. To display constant lines on a chart, assign an array of objects specifying the properties of each constant line to the constantLines field. It is necessary to set the value property within these objects. The other properties can be set if required.

You can customize the appearance of all the value axis constant lines at once. For this purpose, use the valueAxis.constantLineStyle configuration object. Note that the properties that are set within the valueAxis.constantLine object override the corresponding properties that are set within the valueAxis.constantLineStyle object.

constantLineStyle

Specifies the appearance of all the UI component's constant lines.

Use this object to set the appearance properties for the constant lines of both the argument and value axes. For example, you can change the color, dash style and width of the line using corresponding properties or define the look of the labels using the label object.

To specify styles for the constant lines of the argument and value axis separately, use the constantLineStyle object within the argumentAxis or valueAxis configuration object correspondingly. Note that the properties that are set within these objects override the corresponding properties that are set within the commonAxisSettings.constantLineStyle object.

In addition, you can define the appearance of each constant line individually. For more information, refer to the argumentAxis.constantLines or valueAxis.constantLines object description.

discreteAxisDivisionMode

Specifies whether ticks/grid lines of a discrete axis are located between labels or cross the labels.

Default Value: 'betweenLabels'

When a discrete axis is divided, its ticks/grid lines are located between labels by default. If this is not appropriate, use the discreteAxisDivisionMode property to set the required mode for positioning ticks and grid lines on a discrete axis.

NOTE
This property is not designed to work in the spider web mode.

View Demo

endOnTick

Specifies whether to force the axis to start and end on ticks.

Type:

Boolean

Default Value: false

grid

An object defining the configuration properties for the grid lines of an axis in the PolarChart UI component.

Type:

Object

Grid lines are the reference lines used to improve the readability of a chart's visual data. The grid object exposes the properties that allow you to specify visibility and appearance settings for axis grid lines. To learn more about axis grid lines and their properties, refer to the Grid topic.

PolarChart Grid Lines

inverted

Indicates whether or not an axis is inverted.

Type:

Boolean

Default Value: false

When an axis is inverted, the maximum and minimum values are reversed. As a result, the axis values increase in a direction that is opposite to the initial direction. The chart series are also inverted.

View Demo

label

Specifies properties for value axis labels.

Axis labels represent textual values for axis ticks, which are not visible by default. To specify custom settings for the value axis labels, use the label configuration object. If you need to set a common value for labels on all axes, use the commonAxisSettings.label configuration object. This object exposes the properties that can be specified for labels on all axes simultaneously. Note that a value specified for the value axis individually (in the valueAxis.label object) overrides the value that is specified in the commonAxisSettings.label object.

linearThreshold

Specifies a value used to calculate the range on a logarithmic axis within which the axis should be linear. Applies only if the data source contains negative values or zeroes.

Type:

Number

Default Value: undefined

Setting this property prevents generating an infinite number of small axis values. Set it to an integer value that designates a power of logarithmBase. The following code sample shows how different linearThreshold values affect the linear range when the logarithmBase is 10:

JavaScript
linearThreshold: -1 // [-0.1; 0.1]
linearThreshold: -2 // [-0.01; 0.01]
linearThreshold: -3 // [-0.001; 0.001]

View Demo

logarithmBase

Specifies the value to be raised to a power when generating ticks for a logarithmic axis.

Type:

Number

Default Value: 10

By default, ticks on a logarithmic axis are generated on a base of 10, i.e., 0.1, 1, 10, 100, 1000, etc. But you can specify a base you require using the logarithmBase property. For example, if you set this property to 5, the following ticks will be generated: 0.5, 5, 25, 125, 625, etc.

NOTE
The value assigned to the logarithmBase property should be greater than 1.

maxValueMargin

Specifies a coefficient that determines the spacing between the maximum series point and the axis.

Type:

Number

Default Value: undefined

When margins are enabled in a chart, the value axis extends slightly beyond its start and end values. It is required for preventing the cutting off of parts of the minimum and maximum series points.

By default, margins are calculated automatically and equal to half of an axis' tick interval. If you need to specify custom margins, use the minValueMargin and maxValueMargin properties. These properties accept coefficients that are used to calculate the actual start and end values for an axis with applied margins using the following formulas:

startAxisValue = minDataValue - (maxDataValue - minDataValue) * minValueMargin
endAxisValue = maxDataValue + (maxDataValue - minDataValue) * maxValueMargin

For example, consider that minDataValue is 1960 and maxDataValue is 2010. If you set the minValueMargin and maxValueMargin properties to 0.1, the axis will start in 1955 and end in 2015.

startAxisValue = 1960 - (2010 - 1960) * 0.1 = 1960 - 50 * 0.1 = 1960 - 5 = 1955
endAxisValue = 2010 + (2010 - 1960) * 0.1 = 2010 + 50 * 0.1 = 2010 + 5 = 2015

Value Margins ChartJS

NOTE
Margins can be added to axes of the continuous or logarithmic type only.

minorGrid

Specifies the properties of the minor grid.

Type:

Object

In addition to the major grid built on major ticks, the PolarChart UI component provides the minor grid that is built on minor ticks. The lines of the minor grid extend from the minor ticks throughout the entire chart's plot.

NOTE
Neither minor ticks, nor the minor grid can be used if the axis is discrete.

To specify the appearance of grid lines, use the properties of the minorGrid object. Declared within the commonAxisSettings object, the minorGrid object changes the appearance of value and argument axes simultaneously. To change the appearance of the value or argument axis individually, declare the minorGrid object in the argumentAxis or valueAxis object respectively. Settings specified individually override those that are set in the commonAxisSettings object.

To make the minor grid visible, set the visible property of the minorGrid object to true. Additionally, you can change the color, opacity and width of the grid lines using the corresponding properties.

NOTE
We recommend you use the minor grid only in conjunction with the major grid.

minorTick

Specifies the properties of the minor ticks.

In addition to major ticks, the PolarChart UI component provides the capability to draw minor ticks. Minor ticks divide an axis segment that lies between two neighboring major ticks. To specify how to generate minor ticks, use the minorTickInterval or minorTickCount properties.

To configure the appearance of minor ticks, use the properties of the minorTick object. Declared within the commonAxisSettings object, the minorTick object sets properties for all minor ticks. To change the appearance of the minor ticks that belong to the argument or value axis individually, declare the minorTick object in the argumentAxis or valueAxis object respectively. Settings specified individually override those that are set in the commonAxisSettings object.

By default, minor ticks are hidden. To make them visible, assign true to the visible property of the minorTick object. Additionally, you can change the color, opacity and width of the minor ticks using the corresponding properties.

NOTE
Minor ticks cannot be displayed on a discrete axis.

minorTickCount

Specifies the number of minor ticks between two neighboring major ticks.

Type:

Number

Default Value: undefined

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

minorTickInterval

Specifies the interval between minor ticks.

Default Value: undefined

To divide a lengthy chart axis into shorter segments, major and minor ticks are used. Between each pair of neighboring major ticks, several minor ticks reside. Minor ticks are required when major ticks are far from each other. To set a custom minor tick interval, use the minorTickInterval property. If this property is not set, minor ticks are arranged automatically.

In case your axis displays numbers, assign a numeric value to this property. If the axis displays dates, assign one of the predefined string values. To set the interval to several days, hours, etc., assign an object with the corresponding field specified (days, hours or another field). Note that this object must contain only one of the fields described in this section.

NOTE
The minorTickInterval property can be applied to a continuous axis only. For logarithmic axes, use the minorTickCount property.

minValueMargin

Specifies a coefficient that determines the spacing between the minimum series point and the axis.

Type:

Number

Default Value: undefined

When margins are enabled in a chart, an axis extends slightly beyond its start and end values. It is required for preventing the cutting off of parts of the minimum and maximum series points.

By default, margins are calculated automatically and equal to half of an axis' tick interval. If you need to specify custom margins, use the minValueMargin and maxValueMargin properties. These properties accept coefficients that are used to calculate the actual start and end values for an axis with applied margin susing the following formulas:

startAxisValue = minDataValue - (maxDataValue - minDataValue) * minValueMargin
endAxisValue = maxDataValue + (maxDataValue - minDataValue) * maxValueMargin

For example, consider that minDataValue is 1960 and maxDataValue is 2010. If you set the minValueMargin and maxValueMargin properties to 0.1, the axis will start in 1955 and end in 2015.

startAxisValue = 1960 - (2010 - 1960) * 0.1 = 1960 - 50 * 0.1 = 1960 - 5 = 1955
endAxisValue = 2010 + (2010 - 1960) * 0.1 = 2010 + 50 * 0.1 = 2010 + 5 = 2015

MinValueMargin ChartJS

NOTE
Margins can be added to axes of the continuous or logarithmic type only.

minVisualRangeLength

Specifies the minimum length of the visual range.

Default Value: undefined
Cannot be used in themes.

Assign a number to this property if the visual range is set on a numeric axis. If the axis displays date-time values, assign one of the accepted string values or an object to this property. The object should contain one or several fields described in this section, for example:

jQuery
index.js
$(function() {
    $("#polarChart").dxPolarChart({
        // ...
        valueAxis: {
            // ...
            minVisualRangeLength: { weeks: 2 }
        }
    });
});
Angular
app.component.html
app.component.ts
app.module.ts
<dx-polar-chart ... >
    <dxi-value-axis ... >
        <dxo-min-visual-range-length [weeks]="2"></dxo-min-visual-range-length>
    </dxi-value-axis>
</dx-polar-chart>
import { Component } from '@angular/core';

@Component({
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: ['./app.component.css']
})
export class AppComponent {
    // ...
}
import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { AppComponent } from './app.component';

import { DxPolarChartModule } from 'devextreme-angular';

@NgModule({
    declarations: [
        AppComponent
    ],
    imports: [
        BrowserModule,
        DxPolarChartModule
    ],
    providers: [ ],
    bootstrap: [AppComponent]
})
export class AppModule { }
Vue
App.vue
<template>
    <DxPolarChart ... >
        <DxValueAxis ... >
            <DxMinVisualRangeLength :weeks="2" />
        </DxValueAxis>
    </DxPolarChart>
</template>

<script>
import DxPolarChart, {
    DxValueAxis,
    DxMinVisualRangeLength
} from 'devextreme-vue/polar-chart';

export default {
    components: {
        DxPolarChart,
        DxValueAxis,
        DxMinVisualRangeLength
    },
    data() {
        return {
            // ...
        }
    },
}
</script>
React
App.js
import React from 'react';
import PolarChart, {
    ValueAxis,
    MinVisualRangeLength
} from 'devextreme-react/polar-chart';

class App extends React.Component {
    render() {
        return (
            <PolarChart ... >
                <ValueAxis ... >
                    <MinVisualRangeLength weeks={2} />
                </ValueAxis>
            </PolarChart>
        );
    }
}
export default App;
See Also

opacity

Specifies the opacity of the line that represents an axis.

Type:

Number

Default Value: undefined

showZero

Specifies whether or not to indicate a zero value on the value axis.

Type:

Boolean

Default Value: undefined

When this property is not defined, value axis behaves differently depending on the type of the series that it displays. When the value axis displays an area or bar series, it has the zero value indicated. Otherwise, it does not.

You can force the value axis to indicate the zero value no matter what type of series it displays by setting the showZero property to true.

When this property is set to false, the zero value is not indicated until it is included in the displayed series.

strips[]

Specifies properties for value axis strips.

Cannot be used in themes.

Strips are the highlighted areas in a chart within the defined range of values (minimum and maximum) for an axis to which they belong. In general, strips are used to visually represent a range of values behind a series to trace whether the series points' values fall in or out of that range. For more details on strips, refer to the Strips topic.

To define strips for the value axis, use the strips array. When a strip's startValue, endValue and color properties are specified, the strip is displayed in a chart. In addition, you can show a label with descriptive information on a strip. To set the text for a label, use the strip's label object.

If you need to set similar values for all strips of all axes, use the commonAxisSettings.stripStyle configuration object. It exposes the properties that can be specified for strips of all axes at once. Note that the values specified for the value axis individually (in the valueAxis.strips object) override the values that are specified for all axes (in the commonAxisSettings.stripStyle object).

stripStyle

An object defining configuration properties for strip style.

Strips are the highlighted areas of a chart within a defined range of values (maximum and minimum) for an axis to which they belong. In general, strips are used to visually represent a range of values behind a series, to trace whether the series point values fall in or out of that range. For more details on strips, refer to the Strips topic.

To set properties for configuring strip style, define the stripStyle object within the argumentAxis or valueAxis configuration object. To set common properties for all strips in a chart, define the stripStyle object within the commonAxisSettings configuration object. Note that the values that are set for an individual axis override the corresponding common values.

tick

Ticks divide an axis into equal sections by a step whose value is determined automatically, or by the tickInterval and axisDivisionFactor properties of an axis. Ticks improve the readability of charts, but are not visible in the PolarChart UI component by default. To set up tick configuration properties, define the tick object within the argumentAxis or valueAxis configuration object. To set common properties for all ticks in a chart, define the tick object within the commonAxisSettings configuration object. Note that the values that are set for an individual axis override the corresponding common values.

tickInterval

Specifies an interval between axis ticks/grid lines.

Default Value: undefined

Use this property to divide the scale by ticks in a specified interval from each other. If this property is not set, ticks are automatically arranged so that their labels do not overlap each other.

In case of a continuous or a logarithmic axis, assign a numeric value to this property.

If the axis is of the date-time type, assign one of the predefined string values or an object to this property. The object's fields specify the number of days, hours etc.

When you use a logarithmic axis, ticks are generated on a base of powers. For example, assume that the logarithm base is 10. Then, if the tick interval is 1, ticks are generated at 0.01, 0.1, 1, 10, 100, 1000, 10000, etc. If the tick interval is 2, ticks are generated at 0.1, 10, 1000, etc.

To set the tickInterval property for several axis at once, use the commonAxisSettings configuration object. To set this property for an individual axis, use the argumentAxis or valueAxis configuration object.

type

Specifies the required type of the value axis.

Default Value: undefined

The 'discrete' type is set when string values are specified in the data source of the chart's series. The discrete value axis is divided by the values (called categories) that are specified in a series' data source. The categories order can be specified by the categories property if the order used in the data source is not appropriate.

The 'continuous' type is set when numeric or date-time values are specified in the series data source. The continuous axis is divided automatically.

The 'logarithmic' type can be set when numeric values are specified in the series data source. The logarithmic axis is useful when you visualize a dataset of rapidly-growing values. Each axis tick represents a particular value that is raised to the next power in turn. This particular value is specified by the logarithmBase property. For example, if you set this property to 5, the following ticks will be generated: 50, 51, 52, 53, etc.

On continuous and logarithmic axes, ticks and grid lines are generated automatically. In addition, you can set a custom tick interval (the tickInterval or axisDivisionFactor properties).

NOTE
If you require a discrete axis when numeric or date-time values are specified in the data source, set the type property to 'discrete' explicitly.

valueMarginsEnabled

Indicates whether to display series with indents from axis boundaries.

Type:

Boolean

Default Value: true

Additionally, if you use a continuous axis, you can specify how far to extend the axis from its maximum and minimum values. Use the axis' minValueMargin and maxValueMargin properties to do this.

valueType

Specifies the desired type of axis values.

Default Value: undefined

The type of the axis values is determined based on the type of the values specified in the corresponding data source field of the chart's series. If numeric values are specified in the series data source, the axis values will also be of the numeric type. The same logic is used when string or date-time values are specified in the data source.

In some scenarios, you may need the type of the values that are specified in the data source to be converted to another type. In this instance, specify the desired type for the axis values using the valueType property.

NOTE
If dates in your data source are stored as strings, make sure that they have a valid format.

visible

Indicates whether or not the line that represents an axis in a chart is visible.

Type:

Boolean

Default Value: true

visualRange

Defines the axis' displayed range. Cannot be wider than the wholeRange.

Type:

Object

|

Array<Number | String | Date>

Raised Events: onOptionChanged
Cannot be used in themes.

This property accepts one of the following:

  • A two-item array

    Specifies the range's start and end. The array can contain a pair of numeric, string, or date-time values, depending on the axis's valueType. You can also set one of the array values to null to specify an open-ended range.

    visualRange: [50, 70]
    // Open-ended range
    visualRange: [null, 70]
  • An object with the startValue and endValue fields

    An alternative to the two-item array.

    visualRange: {
        startValue: 50,
        endValue: 70
    }
    // Open-ended range
    visualRange: {
        startValue: null,
        endValue: 70
    }
  • An object with the length and a startValue or endValue field

    Specifies the range using a start or end value and length.

    visualRange: {
        startValue: 50,
        length: 20
    }
    // ===== or =====
    visualRange: {
        endValue: 70,
        length: 20
    }
  • An object with the length field

    Sets the range of the specified length using the last axis value as the end value.

    visualRange: {
        length: 20
    }

To specify the minimum visual range that a user can set, use the minVisualRangeLength property.

View Demo

See Also

visualRangeUpdateMode

Specifies how the axis's visual range should behave when the PolarChart data is updated.

Default Value: 'auto'

The following modes are available:

  • "auto"
    The applied mode changes depending on the visual range's position on the axis:

    • at the start or middle, then "keep";
    • if set to view the whole range, then "reset" (the visual range remains equal to the whole range).
  • "keep"
    The visual range does not change.

  • "reset"
    The visual range becomes equal to the whole range.

wholeRange

Defines the range where the axis can be zoomed.

Type:

Object

|

Array<Number | String | Date>

Default Value: undefined

This property accepts one of the following:

  • A two-item array

    Specifies the range's start and end. The array can contain a pair of numeric, string, or date-time values, depending on the axis's valueType. You can also set one of the array values to null to specify an open-ended range.

    wholeRange: [50, 70]
    // Open-ended range
    wholeRange: [null, 70]
  • An object with the startValue and endValue fields

    An alternative to the two-item array.

    wholeRange: {
        startValue: 50,
        endValue: 70
    }
    // Open-ended range
    wholeRange: {
        startValue: null,
        endValue: 70
    }
  • An object with the length and a startValue or endValue field

    Specifies the range using a start or end value and length.

    wholeRange: {
        startValue: 50,
        length: 20
    }
    // ===== or =====
    wholeRange: {
        endValue: 70,
        length: 20
    }
  • An object with the length field

    Sets the range of the specified length using the last axis value as the end value.

    wholeRange: {
        length: 20
    }
See Also

width

Specifies the width of the line that represents an axis in the chart.

Type:

Number

Default Value: 1