Components

Pie/Donut Visualization

Part of the data visualization consolidated component. Pie and donut charts are circular charts that display collected values as proportionally sized segments that represent a whole; donut charts have an open center that you can use to display the sum of all the slices of data in the chart. 

Overview

  • Available sinceSan Diego
  • A11YUnavailable
ServiceNow link
Pie/Donut Visualization code documentation

UIB and developer guidance

Figma link
Pie/Donut Visualization Figma component

Figma library with components for designing Workspace.

Anatomy

Learn about the individual parts of pie and donut charts

Pie chart

Anatomy of a pie chart
  1. Pie chart: Circular chart that is for a part-to-whole data analysis
  2. Data label (optional): Combination of a legend, value, or a percentage
  3. Container: Borderless area that contains the chart

Donut chart

Anatomy of a donut chart
  1. Donut chart: Circular chart for a part-to-whole data analysis; it includes an inner circle for displaying data
  2. Total value (optional): Sum of the values of all the slices
  3. Total value label (optional): Supplemental text label
  4. Tooltip (optional): Label and associated value that appear above a slice on hover
  5. Register (optional): Section that identifies the slices in the chart
  6. Container: Borderless area that contains the chart

Usage

Use a pie chart to display individual data segments that are part of a whole. This allows the user to visually compare different data pieces as they relate to each other and to the entire data set. Use 4-6 segments for the best readability. If the number of segments exceeds 10, use a bar chart to visualize the data. If you want to display the total value of the chart, use a donut chart instead of a pie chart.

Types

There are three types of segmented charts: pie, donut, and semi-donut.

Pie and donut

The difference between a pie chart and donut chart is the way you display the data. All slices within a pie chart are solid, whereas the donut chart features an empty space in the center for data.

Semi-donut

Semi-donut charts display in a 180-degree view and fit in a smaller area than a full donut chart. However, the slice size in semi-donut charts is smaller than in a full donut chart with the same number of values.

Example of a semi-donut chart with data labels and the total value displayed in the center]

Configurations

Learn how to customize pie and donut charts by configuring the available properties

Data source

You can select between 3 different data sources for your visualization: system data tables, preconfigured Performance Analytics indicators, and User Experience Analytics. If you are changing your data source, the option list provides suggestions based on previous selections and items that match your search.

Tables

You can select any table from the system to use in your visualization and filter that data. When you apply a table as the data source, a preview list appears showing all available records in that table.

A condition builder above the list enables you to set filter conditions on the data before using it in your visualization. This is useful for limiting the data shown in the chart to only the data you need.

Indicators

Indicators are preconfigured business metrics that assess performance across attributes such as cost, quality, technical risk, investments, user satisfaction, and business value. Indicators are configured in the Performance Analytics application and reflect common measurements that users need. If breakdowns are defined for an indicator, you can apply filter conditions on those values.

User Experience Analytics

Use User Experience Analytics to understand usage and adoption of your web and mobile applications.

Data properties

Data configuration selects and organizes the data you want your users to see from the source. Configuration options in UI Builder depend on whether you select table data or indicators. Some configurations for indicator data sources require that the indicator have breakdowns.

Metric selection

Select the specific data from the data source to display in a pie/donut chart and the label that identifies it. The default aggregation used is Count. You can select a specific field from the data source table to display. If you leave the field empty, all fields are used, depending on any filtering conditions you applied when you selected the data source.

Shows the metric selector popover in which you configure the data agggretation, table field, and label

Grouping data

Grouped charts compare one or more data sets across all categories. “Group By” is used with aggregate functions like Sum, Count, or Average. The function selected tells the data provider how to treat the data when it is grouped. You can select a field (for table data sources) or a breakdown value (for indicator data sources) as the grouping value.
Note: Not all indicator data sources have available breakdown values. Charts that use indicator data sources without breakdown values can’t be grouped.

Component header

The component header displays in the top left and describes what data is shown in the chart. You create the header label and then show or hide it with the controls provided. By default, the header is configured to show, but the content is empty.

Filters

You can configure data visualization to allow the use of individual chart filters and allow a chart to use the filters set on that workspace page. Filters set on the data source always run on the component. The “Follow filter” property, which is set to “true” by default, applies any filters set on the workspace page in addition to those set on the data source. Setting the “Follow filter” option to “false” prevents any filter input from the workspace page.

Data drilldown

You can configure all chart types to enable users to drill down into data directly from a chart by selecting data points, slices, categories, or scores. This enables users to view data such as records and record lists from data tables or KPI data from indicators.

Data updates

You can configure your chart to update automatically or on a defined refresh schedule.

Presentation properties

The presentation properties control the physical appearance of the chart. Use these properties to control how your users consume the data.

Chart border

You can show or hide a bordering box around the chart.

Height

Pie and donut chart size is configured using a height setting expressed in pixels. You can configure any size you want for your visualization. Select the size, based on the amount of data in your chart, the range of values, and the resolution of the data that you want to show. The default chart size is 250 pixels.

Sorting

You can enable a sorting feature that orders the data slices by name or by value, in ascending or descending order. Slice order starts at the top (12 o’clock) position and runs clockwise. Sorting is available for both data source types.

Colors

You select between 3 color schemes: default, color palette, and fixed element color. The fixed element color selection is not available for indicator data sources. The color palette selection provides a list of predefined color schemes in a dropdown list with a search field.

Legend

The legend on a chart shows a label and a value for a segment selected on the graph. The legend position is configurable for the top, bottom, left, and right sides of the chart. You can show or hide the legend.

Examples of the legend and value in different positions on a pie chart

Data labels

Show or hide data labels on the chart. You can configure the labels to indicate the value of each slice, including the percerntage of the whole.

Displays a pie chart with 10 slices with data labels and percentage values

Design recommendations

Learn how to apply pie and donut charts in your design.

accordion with recommended two nested levels
Do

Limit the number of slices to help users focus on a simple proportion at-a-glance for data comparison.

accordion with too many levels
Don’t

Avoid creating too many slices in a pie chart. This adds cognitive overload and makes it difficult for the users to analyze the data.

Shows how legends should be used on a pie chart to avoide label crowding
Do

Use a register instead of data labels when your chart has many slices. Consider using a scrollbar in the container if the register is too tall.

Shows how too many data labels on a pie chart can overlap and make the data impossible to read
Don’t

When a chart contains too many slices, data labels can overlap with one another.

Shows a properly sized pie chart for visually separating data slices
Do

Keep enough space in the display for the legend and the chart when you define the container sizes.

Example of a pie chart that is too small to easily distinguish the data slices
Don’t

Avoid shrinking the chart size to accommodate the register in a display. Smaller charts cause visual strain and make it difficult for the user to compare and contrast the slices.

Shows a pie chart with a tooltip to identify the data slices
Do

Always include data labels or a legend to help users understand the contents of a pie chart.

Shows pie chart without labels to identify data slices
Don’t

Avoid using a pie chart without any type of labels. This makes it difficult for the user to understand the chart’s purpose or context.

Example of a pie chart that uses only one form of data labeling.
Do

Choose only one method for labeling the data in a pie chart.

Shows how cluttered a pie chart is when both data labels and the legend are used
Don’t

Avoid using data labels and a register together. This creates redundant information and adds visual noise. The tooltip appears by default on hover.

Alignment and positioning

Data labels include a leader line, which is connected to the label and positioned in the middle of the slice. The data label positioning depends on where the slice appears in the container and can’t be manually adjusted. The chart is always centered within the container.

Register positioning

If you include a legend, it center-aligns with the chart. You can choose the position of the legend with respect to the chart and align it with any container edge.

Behavior

Learn how pie and donut charts behave when the display changes or a user interacts with the component.

Responsive behaviors

Learn how pie and donut charts respond to changes in a container or display.

Chart positioning

The diameter of a pie chart with data labels uses 65% of the container area from the shortest edge.

Example of how a pie chart adjusts its size in the container when data labels are used

Without data labels, the diameter of a chart is 80% of the container area from the shortest edge.

Example of how a pie chart fills the container without data labels

Data overflow

When the number of data categories exceeds the number of available slices, the last slice in the slice order becomes an “Other” slice. All remaining categories appear in this slice.

Displays a donut chart with the maximum number of slices and the other category for overflow data]

Interactions

If a data selection action is configured for the chart, selecting a data slice launches an action, such as opening a new page or opening a record.

Truncation

Pie and donut chart text doesn’t truncate. Make sure your labels are concise and meaningful.

Usability

Pie and donut charts complie with all internationalization and accessibility requirements.

Internationalization

Labels for pie and donut charts do not localize for right-to-left (RTL) languages.

Accessibility

Learn how to access the actionable elements of pie and donut charts through keyboard interactions and screen readers.

Pie and donut chart tab order

Example of the first tab order if reader table is on

Example of the tab order when the data labels are configured to show and one or more appear truncated

Keyboard interactions

Users can access the chart legend and the chart navigator with these keyboard keys:

  • Tab: Moves focus forward between the chart container, the chart, and the legend
  • Shift + Tab: Moves focus backwards
  • Esc: Dismisses displayed tooltip
  • Enter or space bar: Triggers an action associated with an interactive element when in focus, such as opening a list view for a data point or muting a dataset
  • Arrow up, down, right, left: When the chart has focus, moves focus through the segments starting with the top right; right or down moves focus clockwise; left or up moves counter clock wise. When the legend has focus, moves focus through the legend items
    Navigating large charts quickly:
  • Home: Moves focus to top right (first) segment
  • fn + Arrow up or left: (Mac) Moves focus to top right (first) segment
  • End: Moves focus to last segment
  • fn + Arrow down or right: (Mac) Moves focus to last segment

Screen readers

Pie and donut charts can be configured with an ARIA label to describe to screen reader users what the chart shows. However, the screen reader can’t read the elements of the chart itself. A screen reader can read values from a data table that accompanies the chart via manual use of the arrow keys on the user’s keyboard. Data tables are enabled with an accessibility control in user preferences on the instance and not in the component.

Example of the data table from which the screen reader reads data

This example shows the donut chart data table. The screen reader reads the entries as the user manually navigates the table using the arrow keys.