Cloudscape Docs MCP Server

--- title: "Pie and donut charts - Cloudscape Design System" source: "https://cloudscape.design/components/pie-chart/?tabId=usage" created: 2025-10-01 description: "Pie and donut charts visualize the relationship or correlation between data metrics in a dataset." --- ## Pie and donut charts Published: September 10, 2025 | Last updated: September 8, 2025 [Get design library](https://cloudscape.design/get-started/for-designers/design-resources) [Browse code](https://github.com/cloudscape-design/chart-components/tree/main/src/pie-chart "Browse code (opens new tab)") [View in demo](https://cloudscape.design/examples/react/dashboard.html "View in demo (opens new tab)") These new chart components are built on top of Highcharts, which is a [commercial third-party library](https://www.highcharts.com/). Refer to the [licensing section on Charts](https://cloudscape.design/components/charts/#licensing) for more details. ## General guidelines ### Do - When defining segment colors, ensure that the order of colors defined in the [color palette](https://cloudscape.design/foundation/visual-foundation/data-vis-colors/) is maintained across the order of segments in the pie or donut chart. - Use a pie or donut chart to visualize up to five data metrics. If more than five data metrics need to be visualized, use a [stacked bar chart](https://cloudscape.design/components/cartesian-chart/?tabId=playground&example=bar-chart%3A-multiple-data-series%2C-stacked) instead. - Try to limit the number of items in a metric breakdown to seven to help conserve space. Prioritize content that adds value to the user. ### Don't - Don't use a pie or donut chart to visualize time series. Use a [bar chart](https://cloudscape.design/components/cartesian-chart/?tabId=playground&example=bar-chart%3A-single-data-series) or [line chart](https://cloudscape.design/components/cartesian-chart/?tabId=playground&example=line-chart%3A-single-data-series) instead. - Don’t use a pie chart to visualize a single data metric as they are meant to show part-to-whole relationship which needs at least 2 metrics. - Avoid truncating names describing data metrics. If truncation is necessary, ensure that unique identifiers included in the string are visible to users. For example: a chart showing S3 resources where segment labels include long ARNs. Ensure that the portion of an ARN which helps users identify the resource is visible after truncation. - In chart series detail don't add links to both metric key and metric value. Instead, pick one or the other. ## Features Pie and donut charts depict part-to-whole relationships between data metrics in a data set. They represent data for a snapshot of time. - #### Chart types - **Pie chart**: A pie chart helps users see the relationship between different data metrics in a data set. - For example: A pie chart showing the distribution of resources by compliance status. - **Donut chart**: A donut chart is a variant of a pie chart with its center removed. The empty area in the center of this chart is used to display a metric corresponding to the sum or net value of all metrics visualized in the chart. - For example: A donut chart showing the distribution of revenue generated from five different products. The total revenue generated by all five resources is displayed in the center of the donut. - #### Segments Individual metrics in a data set are shown as segments. The size of a segment is relative to the value of data metric it represents. There is a minimum segment size to ensure all available metrics are visible, even if the metric is a relatively small part of the total. Data metrics of zero value will not show as a segment. Arrange segments starting at the 12 o’clock position in clockwise direction, in one of the following orders: - **Decreasing order of size:** The segment of largest size is shown first, followed by smaller segments in the decreasing order of size. - For example: In a donut chart showing the breakdown of total expenses, the segment representing the largest expense is shown first, and the smallest expense is shown last. - **Inherent order of metrics:** If the metrics in a data set have an inherent ranking or order, arrange the segments in that order, irrespective of the size of each segment. - For example: In a pie chart showing resources categorized by severity, the segments are arranged in a decreasing order of severity from critical to low. - #### Segment label title - optional Provide a name or description for the associated data metric in the segment label title. This helps to make the chart more accessible to users with low vision or color blindness as they can identify data using these labels. These titles correspond to the labels displayed in the legend. Since the segment labels don't wrap dynamically, they might not be visible in smaller viewports. - #### Segment label description - optional Display the associated metric value and percentage next to each segment. This helps users interpret the chart better. If users filter data that changes segment size of visualized data metrics, the new percentage should be displayed in the segment label description. - #### Inner metric value - optional Use the empty area inside a donut chart to display the total or net value of all data metrics visualized in the chart. The inner metric value can be used to display: - Sum of all data metrics visualized in the chart. If a user filters out some data metrics, show the new sum. - For example: Total cost of all services used this month. - If the chart is focused on one primary metric, such as percent complete or score, show that metric rather than the sum. - For example: Average security score of a resource. - #### Inner metric description - optional Provide an additional unit or short description corresponding to the inner metric if needed. Due to limited area inside a donut chart, the content displayed here should be concise. - #### Details popover Information about a segment such as the name, value, and percentage of the associated data metric are displayed in a popover as key-value pairs, use [links](https://cloudscape.design/components/link/) or text. By default, the associated value and percentage is displayed for each segment. More key-value pairs can also be displayed to better understand the breakdown of a segment's data. There are two main ways to interact with the details popover: - **On hover:** When a user hovers on the data area, the popover shows the name and value for each data point. - **On select:** If a user selects the data area, the popover fixes in position. This works well for assistive devices and devices without hover states. **Metric breakdown and drill down** When there is additional information that makes up a metric, these can be displayed as key-value pairs that are nested under a metric that is made up of related child metrics. This can be either be listed as key-value pairs or placed in an expandable section to conserve space. For example: - A nested grouping of related child services under a parent key of *other services*. - A list of accounts that contribute to a combined metric value of its parent. With links, you can provide access to a break down of more details on a new page. - **Link in the Key:** Add an external link, which opens details in a new page. For example linking to a specific account to view customer details. - **Link in the Value:** Add an external link to a value to provide a drill down into the value. For example, linking to a full page table to view a filtered list of accounts that are in an error state. **Sizes** The details popover supports all popover sizes. Use the appropriate popover size based on the amount of information you want to display, such as the length of associated labels. **Popover footer** To enable additional actions and drill down on the selected metric you can use the footer area of the popover. Use the footer to add: - **Actions:** Up to two buttons. When you have more than two buttons group these in a button dropdown to conserve space. - **Drill down:** Drill down functionality such as filters and text. See [chart metric drill down](https://cloudscape.design/patterns/general/data-vis/chart-metric-drill-down/) for further information. - #### Legend - optional Displays a list of all metrics in the source data set. A legend item comprises a visual indicator with an adjoining text label describing the metric. A legend is required when the data set contains metrics with a value of zero. Since metrics with a zero value are shown in the legend, but not visualized in the chart, having a legend provides users an overview of all measured metrics. A legend is optional when all data metrics in a data set are visualized and the segments are annotated using segment labels, as it provides no additional information to the user. - #### Legend title - optional Use the legend title to briefly describe the legend items. The legend title is not required when sufficient descriptive information about the legend is provided elsewhere on the page, such as the chart title or page title. - #### Built-in filter - optional The chart component has a built-in filter. With it, users can select which data metrics show on the chart. By default, all data metrics in the source data are selected to show on the chart. Use a filter in a pie or donut chart when the source data set has at least three data metrics. - #### Additional filters - optional To support users’ data exploration needs, you can add more filters in the chart component. For example: A [date picker](https://cloudscape.design/components/date-picker/) so users can filter data based on different periods of time. ### States - #### Loading The state of fetching data prior to the visualization being displayed. Show loading state text when the component is in this state. - #### Error The state of the component when it fails to fetch data. Display error state text and provide a recovery action as a recovery mechanism. - #### No match The state of visualization when there is no data to display after a user applied filters. Display no match state text and provide an action button to revert to the default state of the visualization. - #### Empty The state of the component when there is no data to display. It could occur when the source data set has no metrics*.* Display empty state text when the component is in this state. ## Writing guidelines - Use sentence case, but continue to capitalize proper nouns and brand names correctly in context. - Use end punctuation, except in [headers](https://cloudscape.design/components/header/?tabId=usage) and [buttons](https://cloudscape.design/components/button/?tabId=usage). Don’t use exclamation points. - Use present-tense verbs and active voice. - Don't use *please*, *thank you*, ellipsis (*...*), ampersand (*&*), *e.g.*, *i.e.*, or *etc.* in writing. - Avoid directional language. - For example: use *previous* not *above*, use *following* not *below*. - Use device-independent language. - For example: use *choose* or *select* not *click*. ### Component-specific guidelines #### Chart title - Use nouns to describe what the visualization contains. - For example: *Monthly bill* or *Compliance details* #### Segment label description - Use the format *\[numeric value\] \[description or unit\], \[percentage value\]* - For example: *245 Gigabytes*, *36%* or *20 items*, *20%* #### Details popover - When providing additional key-value pairs, use the format *\[key\] \[value\]* - For example: *Value 200*, *Percentage 20%*, or *Total 1000* #### Legend title - Use nouns to describe what items the legend contains. - For example: *Resource status* #### Built-in filter - For placeholder, use this text: *Filter data* #### Inner metric - When applicable, include relevant typographic symbols with numeric values, such as currency denomination or degree symbol for temperature. - For example: *$4000* #### Inner description - Be concise, typically one to two words. - If relevant, include the associated unit in the description. - For example: *Revenue (USD)* #### Loading state - Use this text: *Loading chart* - Follow the guidelines for [loading states](https://cloudscape.design/patterns/general/loading-and-refreshing/). #### Error state - **Error message** - Use this text: *The data couldn't be fetched. Try again later.* - Follow the guidelines for [validation](https://cloudscape.design/patterns/general/errors/validation/) and [alert](https://cloudscape.design/components/alert/). - **Recovery action** - Use this text: *Retry* - Follow the writing guidelines for [button](https://cloudscape.design/components/button/?example=primary-button&tabId=usage#writing-guidelines). #### No match state - **Heading** - Use this text: *There is no matching data found* - Follow the guidelines for [empty states.](https://cloudscape.design/patterns/general/empty-states/) - **Description** - *optional* - Explain why the data wasn't found. - For example: *There is no matching data to display.* - **Action button** - Provides an action button to set the visualization back to the default state. This should always be a [secondary button](https://cloudscape.design/components/button/?example=normal-button). - Use this text: *Clear filter* - Follow the writing guidelines for [button](https://cloudscape.design/components/button/?example=primary-button&tabId=usage#writing-guidelines). #### Empty state - **Heading** - Use this text: *There is no data available* - Follow the guidelines for [empty states.](https://cloudscape.design/patterns/general/empty-states/) - **Description** \- *optional* - Explain why there is no data available. - For example: *There is no data available in the source data set.* ## Accessibility guidelines - Follow the guidelines on alternative text and Accessible Rich Internet Applications (ARIA) regions for each component. - Make sure to define ARIA labels aligned with the language context of your application. - Don't add unnecessary markup for roles and landmarks. Follow the guidelines for each component. - Provide keyboard functionality to all available content in a logical and predictable order. The flow of information should make sense. ### Component-specific guidelines - For the default filter, follow the guidelines for [multiselect accessibility](https://cloudscape.design/components/multiselect/?example=default&tabId=usage). - Use an accessible color palette for visualizations. Follow the guidelines for [data visualization color](https://cloudscape.design/foundation/visual-foundation/data-vis-colors/#accessibility-guidelines). #### Alternative text - Provide alternative text for the chart. Use `ariaLabel` to give the chart a label that matches its visible title, for example from the container header. - Additionally, provide an alternative chart description through the `ariaDescription` property. Use the format: *\[Chart type\] showing the \[data displayed\].* If applicable, also include the timeframe for the data displayed. - For example: *Line chart showing the number of critical resource errors in the last one month.*