PieChart Elements

Topics in this section describe PieChart widget elements. Each topic gives an overview of an element's purpose, and details ways to enable and tune it to your needs.

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

Tooltip Series Point
Series Point
Series Point
Series Point
Series Point
Series Point
Series Point
Series Label Series Label Series Label Series Label Series Label Series Label Series Label Title Legend

Series

A Series represents a group of related data points. The most important characteristic of a series is its type, which determines a particular visual representation of data. The pie chart series types are used to illustrate value proportion via circular sectors. You can find more details on each series type in the corresponding topics in the PieChart Series Types section. Here, you will learn how to set a series type and other series options.

PieChart Series

There can be only one series in the dxPieChart widget. The series data points are represented by circular sectors. To set a series type, use the type property of the series configuration object.

JavaScript
$("#pieChartContainer").dxPieChart({
    series: {
        type: 'doughnut'
    }
});

To set data for a series, there are several approaches. You can set a common data source for all series or specify data for each series individually. For details, refer to the Data Binding section.

The series configuration object can also be used to set options for the series labels. In addition, you can specify custom settings for displaying series points (slices) when they are hovered over or selected.

JavaScript
$("#pieChartContainer").dxPieChart({
    series: {
        label: { visible: true },
        hoverStyle: {},
        selectionStyle: {}
    }
});

Series Points

A series point is a visual representation of a data point. In a pie chart, series points are displayed as circular sectors. The size of the sector depends on the value proportion of the series point relative to the other series points.

PieChartSeriesPoints

Several point options that you can specify are categorized and listed as follows.

  • Appearance
    By default, pie slices are displayed using the colors from the default palette. You can set a custom palette with the palette option. Alternatively, set a single color for all slices at once using the color option.
    Direct the chart slices the way you want using the segmentsDirection option.

  • Border
    Change the visibility of the slice borders using the visible option of the border object. In addition, set a custom color and width using the border's color and width options.

  • Hover Options
    The appearance of a pie slice is changed when it is hovered over. You can paint the hovered slice in another color, apply hatching to it and change the style of the slice border using the options of the hoverStyle object.

  • Selection Options
    Set a custom color, hatching and border settings for selected pie slices. For this purpose, define the corresponding options in the selectionMode object.

Series points can be accompanied with series labels. For further information, refer to the Series Point Labels topic.

Series Point Labels

Each series point can be accompanied with a series label. These labels display data related to the point. It can be the point's argument, value or both. You can customize the label text, if it is required.

PieChartSeriesPointLabels

By default, series labels are not displayed. To make them visible, set the visible option of the label object to true.

JavaScript
$("#pieChartContainer").dxPieChart({
    series: {
        label: {
            visible: true
        }
    }
});

To change the default label settings, specify the required options within the label configuration object. Several of these options are categorized and listed below.

  • Arrangement
    Use the position option to alter the point label location. In addition, you can change the distance between the labels and the chart using the radialOffset option and rotate the labels with the rotationAngle option.

  • Text Customization and Formatting
    By default, labels show the point values without formatting. Set the argumentFormat and argumentPrecision options to format the argument, and the format and precision options to format the value. In case text customization is required, assign a function returning the text to be shown to the customizeText option. Learn more in the Data Formatting topic.

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

  • Appearance
    Paint the labels in a required color using the backgroundColor option. To change the style of the label border, define the border settings within the border configuration object. In addition, you can display labels with connectors. For this purpose, set the options within the connector object.

Tooltips

A tooltip is a small pop-up rectangle that displays information on a hovered series point. By default, a tooltip shows the point's value. However, it is possible to display other information in a tooltip. You can customize the text of a tooltip or its appearance in the way you require.

PieChartTooltip

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

JavaScript
$("#pieChartContainer").dxPieChart({
    tooltip: {
        visible: true
    }
});

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

  • Appearance
    You can paint a tooltip in the color of your choice with the tooltip's color option. To set the distance between the text and borders of a tooltip, use the paddingLeftRight and paddingTopBottom options. In addition, you can alter the length of the tooltip's arrow by changing the arrowLength option.

  • Text Customization and Formatting
    By default, tooltips show the point values without formatting. Set the argumentFormat and argumentPrecision options to format the argument, and the format and precision options to format the value. In addition, you can display the slice value as a percentage with a specified precision. For this purpose, use the percentPrecision option. When text customizing is required, assign a function returning the text to be shown to the customizeText 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.

  • Tooltip Event Related Functions
    You can perform specific actions when showing/hiding a tooltip. For this purpose, assign a function to the tooltipShown and/or tooltipHidden options. Note that these options are located in the root of the chart's configuration object

You can force a point's tooltip to show or hide using the showTooltip() or hideTooltip() method. To hide the tooltip without accessing a point, call the hideTooltip() method of the chart's instance.

Show Example:
jQuery

Legend

The dxPieChart widget can include a legend - an explanatory component, which helps you distinguish one series from another on the chart plot. Each series is represented on a legend by an item. An item marker identifies the color of a pie slice. An item label represents the argument of the corresponding point.

PieChartLegend

You can tune the legend options within the legend configuration object. See the list below to learn information on some of these options.

  • Legend Appearance
    To change the legend's visibility, use the visible option. Set the backgroundColor option to change the color of the legend background.

  • Items Arrangement
    Legend items are displayed in columns and rows. To set the number of the items in a column or a row, use the columnCount or rowCount options. The rows and columns must be placed within a legend separated by a space from one another and from the legend's border. To specify this spacing, use the columnItemSpacing, rowItemSpacing, paddingLeftRight and paddingTopBottom options. In addition, you can set the equalColumnWidth option to true if you want all columns to have the width of the widest column.

  • Items Appearance
    Change the itemTextPosition option to set a suitable location of the item text relative to the item marker. Specify the markerSize option to make an item marker smaller or bigger.

  • Location
    A legend can be located in different places on a chart. You can adjust a legend's position using the horizontaAlignment and verticalAlignment options. Also, spacing between a legend and neighboring chart elements can be specified with the margin option.

  • Border
    Change the visibility of the legend borders by specifying the visible field within the legend | border object. You can round border corners with the cornerRadius option and alter the dash style of the legend border using the dashStyle option. In addition, a custom color and width can be set using the border's color and width options.

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

  • Hover Options
    Pie slices can be highlighted when the corresponding legend item is hovered over. To manage this behaviour, use the legend's hoverMode option.

Chart Title

The dxPieChart widget can be displayed with a title. These titles usually contain general explanations about the data represented by that chart. You can, however, place any kind of information in the chart title.

PieChartTitle

To set a chart's title, use the title option. If you do not need to change any title options except text, assign the required text directly to the title option, as it is demonstrated in the code below.

JavaScript
$("#pieChartContainer").dxPieChart({
    title: 'Area of Continents'
});

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

JavaScript
$("#pieChartContainer").dxPieChart({
    title: {
        text: 'Area of Continents',
        font: {
            size: 30,
            weight: 100
        }
    }
});

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

  • Title Location
    You can place a title to any side of the chart. For this purpose, use the horizontalAlignment and verticalAlignment options.

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