Visual 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.

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

Series

A Series represents a group of related data points. The most important characteristic of a series is its type, which determines the specific visual representation of data. The pie chart series types are used to illustrate value proportion with 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 Single-Series PieChart Multi-Series

The PieChart widget supports multiple series, which are presented as concentric circles. Each series is configured using an object in the series array. To set the series type, specify the type field of this object.

JavaScript
var pieChartOptions = {
    // ...
    series: [{
        type: 'doughnut'
    }, {
        // ...    
    }]
};

To provide data for a series, set a common data source. For details, refer to the Data Binding article.

Using the series configuration object, you specify options for other series-related chart elements - series points and labels. Move on to the next topic for more information.

View Demo

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 labels. For further information, refer to the Series Point Labels topic.

Series Point Labels

Each series point can be accompanied with a 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, point labels are not displayed. To make them visible, set the visible option of the label object to true.

JavaScript
var pieChartOptions = {
    // ...
    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 option to format the argument, and the format option 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, by default, displays the value of the series point hovered over. It is, however, possible to display other information in a tooltip by customizing the text of a tooltip or its appearance as required.

PieChartTooltip

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

JavaScript
var pieChartOptions = {
    // ...
    tooltip: {
        enabled: 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 option to format the argument, and the format option to format the value. In addition, you can display the slice value as a percentage with a specified precision. For this purpose, use the format | percentPrecision option. When text customizing 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.

  • Tooltip Event Related Functions
    You can perform specific actions when showing/hiding a tooltip. For this purpose, assign a function to the onTooltipShown and/or onTooltipHidden 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:
AngularJS
Knockout
jQuery

Legend

The PieChart 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 specify how to arrange legend items use the orientation option. 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.

  • 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 PieChart 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
var pieChartOptions = {
    // ...
    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
var pieChartOptions = {
    // ...
    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.

You can also configure the chart subtitle using the subtitle object.