0.5.8 [Current]

PieChart

import { PieChart } from '@concur/nui-charts';

A pie chart is a circular statistical graphic which is divided into slices to illustrate numerical proportion. In a pie chart, the arc length of each slice (and consequently its central angle and area), is proportional to the quantity it represents.

Best Practices

• Visualize no more than 5 categories per chart. It is difficult to differentiate between small values; depicting too many slices decreases the impact of the visualization. If needed, you can group smaller values into an “other” or “miscellaneous” category, but make sure it does not hide interesting or significant information.
• Don’t use multiple pie charts for comparison. Slice sizes are very difficult to compare side-by-side. Use a stacked bar chart instead.
• Make sure all data adds up to 100%. Verify that values total 100% and that pie slices are sized proportionately to their corresponding value.
• Order slices correctly. There are two ways to order sections, both of which are meant to aid comprehension:
  • Option 1: Place the largest section at 12 o’clock, going clockwise. Place the second largest section at 12 o’clock, going counterclockwise. The remaining sections can be placed below, continuing counterclockwise.
  • Option 2: Start the largest section at 12 o’clock, going clockwise. Place remaining sections in descending order, going clockwise.

Example

For PieChart, each data point will be defined by a PieChart.Pie child component.

const data = [
    { name: 'Project A', code: 'ABCD-123-XYZ', value: 250 },
    { name: 'Project B', code: 'EFGH-001-XYZ', value: 125 },
    { name: 'Project C', code: '7781-220-010-A', value: 89 },
    { name: 'Project D', code: 'LMNO-664-STU', value: 160 },
    { name: 'Project E', code: '5562-008-030-E', value: 20 }
];

<PieChart
    textNoData='No data'
    title='Project Allocations'>
    <PieChart.Pie
        data={data}
        dataKey='value'
        dataKeyLabel='Amount'
        nameKey='name'
        nameKeyLabel='Project'
        valueFormatter={formatCurrencyNoDecimal} />
</PieChart>

Keys: Data Table vs Legend

Data Table

By default, a Data Table is automatically generated in conjunction with the chart. While visually similar to a traditional legend, the data table provides colorblind users and users of screen readers with crucial content and data that they may not be able to gain from the chart itself. (See Accessibility for more details.)

The data table can be positioned in different locations relative to the chart. Use the tableLegendPosition property to set the position.

const dataReports = [
    { status: 'No Exceptions', count: 74 },
    { status: 'With Exceptions', count: 13 }
];

const dataBudgetPie = [
    { name: 'Spend', value: 2521.43 },
    { name: 'Pending', value: 597.5 },
    { name: 'Available', value: 907.07 }
];

<PieChart
    tableLegendPosition={{
        placement: 'bottom',
        justify: 'center'
    }}
    textNoData='No data'
    title='Report Summary'>
    <PieChart.Pie
        data={dataReports}
        dataKey='count'
        dataKeyLabel='Number of Reports'
        nameKey='status'
        nameKeyLabel='Status' />
</PieChart>

<PieChart
    tableLegendPosition={{
        placement: 'left',
        justify: 'start'
    }}
    textNoData='No data'
    title='Budget'>
    <PieChart.Pie
        data={dataBudgetPie}
        dataKey='value'
        dataKeyLabel='Amount'
        nameKey='name'
        nameKeyLabel='Type'
        outerRadius='100%'
        valueFormatter={formatCurrency} />
</PieChart>

Legend

If there is already a data table on the page, or if you intend to display a data table when a user clicks a trigger (link), you may use the traditional Legend that only displays category labels and associated colors.

The traditional legend can also be positioned in different locations relative to the chart. Use the imageLegendPosition property to set the position.

Customizations

NUI Charts is intended to give consumers a simple, easy-to-use API for generating default charts. However, there are a number of customizations that consumers can use to access the full capability of the underlying chart library.

The example below shows a number of customizations:

• Showing the chart’s legend (Not the data table. See Keys: Data Table vs Legend for the difference) with custom positioning and icon shapes
• Showing the tooltip with custom styling
• Using a separate data table in place of the auto-generated companion data table

See Recharts.org for more information about customizations.

const data = [
    { name: 'Project A', code: 'ABCD-123-XYZ', value: 250 },
    { name: 'Project B', code: 'EFGH-001-XYZ', value: 125 },
    { name: 'Project C', code: '7781-220-010-A', value: 89 },
    { name: 'Project D', code: 'LMNO-664-STU', value: 160 },
    { name: 'Project E', code: '5562-008-030-E', value: 20 }
];

<PieChart
    imageLegendPosition={{
        verticalAlign: 'bottom',
        align: 'center'
    }}
    imageLegendProps={{
        iconType: 'triangle',
        layout: 'horizontal'
    }}
    showImageLegend
    showTooltip
    tableLegendExternalId='custom-table'
    textNoData='No data'
    title='Project Allocations'
    tooltipProps={{
        separator: ' = ',
        wrapperStyle: {
            backgroundColor: '#333',
            borderRadius: '4px'
        },
        labelStyle: {
            color: '#ccc',
            fontSize: '18px',
            fontWeight: 'bold'
        },
        itemStyle: {
            color: '#fff'
        }
    }}>
    <PieChart.Pie
        data={data}
        dataKey='value'
        dataKeyLabel='Amount'
        nameKey='name'
        nameKeyLabel='Project'
        valueFormatter={formatCurrencyNoDecimal} />
</PieChart>

<DataGrid
    columns={[
        { propertyName: 'name', headerContent: 'Project Name' },
        { propertyName: 'code', headerContent: 'Project Code' },
        {
            propertyName: 'value', align: 'right', headerContent: 'Amount', bodyContent: (row) => {
                return formatCurrencyNoDecimal(row.value);
            }
        }
    ]}
    data={data}
    empty={{
        title: 'No data'
    }}
    id='custom-table' />

Usage

PieChart

Properties

Shape: tableLegendPosition

Properties

Shape: imageLegendPosition

Properties

PieChart.Pie

Properties

Callbacks

See Recharts.org for more information.

Accessibility

Consumers of pie charts must:

• Provide a relevant title for all charts and graphs
• Utilize the default data table to ensure that all non-text content that is presented to the user has a text alternative that serves the equivalent purpose

By default, CoreUI components help assistive technology read a pie chart’s content by building the following into the default component:

• When utilizing charts and graphs, keep in mind that all non-text content that is presented to the user has a text alternative that serves the equivalent purpose. Additionally, tables of data must not be turned into images. Utilize the default data table to ensure this guideline is met.
• Colors are provided to ensure that color not only meets proper color contrast requirements, but that they aren’t used as the only visual means of conveying information, indicating an action, prompting a response, or distinguishing a visual element.

Resources

• Data 101
• Pie Charts 101
• WCAG 2.0 Guidelines for Non-text Content
• WCAG 2.0 Guidelines for Supplemental Color-coding of Charts