CircularChart handbook

License: Before reading component documentation, source, or npm usage instructions for the first time, read the full LICENSE. Reuse that review for the same task and version. Public API configuration and internal implementation changes have different license implications. All components use the unified runtime package; source rights remain governed by the license.

Overview

Show proportions in a ring or pie chart, with segments, rounded corners, ring thickness, and hover emphasis for composition analysis.

When to use it

Use CircularChart for proportions in a ring or pie. Choose GaugeChart or Progress for completion metrics according to their semantics. Configure colors and labels through public props.

• Data uses name and finite positive value; only the previous maxItems valid items are displayed, and the score is the sum of these display items. The explicit empty array shows the empty picture.

• It is recommended to use the number size; string geometry only takes the numerical part, and cannot rely on percentage or CSS variables to complete the adaptation. The central content uses the public center-label / segment-value / segment-name role.

• The default root accessible name follows LocaleProvider through circularChart.name; an explicit aria-label takes priority. Business names, data values, and numeric formatting remain controlled by the caller.

Quick start

This example shows the recommended basic composition. See the sections below for more cases and composition limits.

<script lang="ts">	import { Button, Frame, Icon, Text } from '@snowui-design-system/components';	import { DotCircle } from '@snowui-design-system/resource-svelte';	import { CircularChart } from '@snowui-design-system/components';	// Illustrative SnowUI site visits over the last 30 days; these are not actual statistics.	const channels = [	    { name: 'Search', value: 12840, color: 'var(--primary)' },	    { name: 'Direct', value: 8560, color: 'var(--secondary-purple)' },	    { name: 'GitHub', value: 5350, color: 'var(--secondary-cyan)' },	    { name: 'Figma', value: 4280, color: 'var(--secondary-mint)' },	    { name: 'Community', value: 3210, color: 'var(--secondary-green)' }	];	const total = channels.reduce((sum, item) => sum + item.value, 0);	let trafficChart: { replay: () => void; reverseAppearance: () => void } | undefined;</script> <div style="display: flex; flex-direction: column; align-items: center; width: var(--size-full); gap: var(--gap-4) var(--gap-3);">    <div style="display: flex; align-items: center; justify-content: center; flex-wrap: wrap; min-width: 0; max-width: var(--size-full); gap: var(--gap-4) var(--gap-7);">        <CircularChart bind:this={trafficChart} data={channels} ringThickness={48} appearOnView defaultAppearanceProgress={0} role="group" aria-label="SnowUI website visits by source, sample last 30 days" />        <div style="display: flex; flex-direction: column; gap: var(--gap-3);">            <div style="display: flex; flex-direction: column; gap: var(--gap-0);">                <Text style="font-size: var(--text-18); line-height: var(--leading-18); color: var(--black-100); font-weight: 600;">Website traffic</Text>                <Text style="font-size: var(--text-12); line-height: var(--leading-12); color: var(--black-40);">Sample · last 30 days · {total.toLocaleString('en-US')} visits</Text>            </div>            <div style="display: grid; grid-template-columns: auto auto; align-items: center; gap: var(--gap-2) var(--gap-6);">    {#each channels as item}        <Frame singleLine gap={0}><Icon as="leading" size={12} style={`color: ${item.color};`}><DotCircle weight="fill" /></Icon><Text lines={1} style="font-size: var(--text-14); line-height: var(--leading-14); color: var(--black-100);">{item.name}</Text></Frame>        <Text style="font-size: var(--text-14); line-height: var(--leading-14); color: var(--black-100); text-align: right; font-variant-numeric: tabular-nums;">{item.value.toLocaleString('en-US')}</Text>    {/each}</div>        </div>    </div>    <div style="display: flex; align-items: center; justify-content: center; flex-wrap: wrap; gap: var(--gap-4) var(--gap-3);">        <Button onclick={() => trafficChart?.replay()}>Replay animation</Button>        <Button onclick={() => trafficChart?.reverseAppearance()}>Reverse animation</Button>    </div></div>

API

See the base component documentation for inherited capabilities not redeclared here. This table lists only named public Props declared by this component.

Usage boundaries and details

HoverPanel shares a three-column layout. The dot-to-name gap prefers --gap-1 and the name-to-value gap prefers --gap-2; both retain a 4 CSS px floor in LTR and RTL. At a 16px root font size the defaults remain 4px / 8px, and larger tokens are preserved. This floor does not apply to vertical panel sections or chart center annotations.

Design principle

• Professional chart components: The current maintenance location is components/src/components/; this directory is the technical location during the migration period. THE RUNNING PACKAGE AND ORIGINAL SOURCE CODE OF ALL COMPONENTS CAN BE OBTAINED FREE OF CHARGE; THE PURPOSE, PROJECT, SEAT AND PRODUCTION USE RIGHTS AND INTERESTS ARE EXECUTED ACCORDING TO LICENSE, AND COMPONENTS ARE NOT DIVIDED ACCORDING TO ADVANCED FUNCTIONS.

• Up to 10 items: Default maxItems=10. The color only uses primary and 9 secondary-* tokens. After 10 items, the color will be repeated and the recognition of the chart will decrease, so the component is truncated to 10 items by default.

• Color mode: Default colorMode="sequence" press primary → secondary-purple → secondary-cyan → secondary-mint → secondary-green → secondary-indigo → secondary-blue → secondary-yellow → secondary-orange → secondary-red cycle; monochromeFade uses Primary from 100% to the last 20%; monochrome defaults to use Black4 in all sectors. Each data item can define the sector color separately by color; colors can be used as a color palette overlay entry by index, and the blank item can be returned to the current color mode.

• Geometric scaling: The values of cornerRadius and separatorWidth are both design reference values under the 160x160 chart, and the components will be scaled according to the actual size / 160 equiproportio. auto uses the default reference value: rounded corner 4, interval 2.

• Hover emphasis: When hover / focus is the current item, the sector is not displaced, and only the outer radius slows down to increase hoverThicknessGrowth, and the default outward thickness is 4px; the percentage is displayed above the center label, and the name of the current item is displayed below.

2.1 Data and form

• Support ring chart and solid pie chart: when ringThickness is less than the outer radius, it is a ring, and when ringThickness >= outerRadius, the inner radius is zero and a solid pie chart is formed.

• Support up to 10 sectors: maxItems defaults to 10, the internal upper limit is fixed at 10, and the excess items will be truncated.

• Automatically filter invalid data: value <= 0 or non-numeric items do not participate in rendering; render empty charts when explicit empty arrays or all invalid, and only use built-in sample data when data is omitted.

• Support size, ring thickness, rounded corner, partition and hover outer thickening adjustment: digital values are written to component private CSS variables according to px semantics.

• Support 160x160 reference geometry scaling: the incoming values of cornerRadius and separatorWidth are both design reference values, and the actual rendering is enlarged or reduced in equal ratio of size / 160.

2.2 Sector drawing

• The sector path includes the outer arc, the inner arc and the rounded corners of the head and tail tangent. The rounded corners are generated according to the shape of the real sector and do not depend on the later cutting.

• The transparent interval between sectors is generated in the path geometry stage: separatorWidth will be converted to padAngle of d3-shape, and the inner and outer arc will be contracted with padRadius. Do not draw white divides, and do not use the rear gap mask to hollow out the sector.

• The rounded corner is still generated by the contracted sector path, so the transparent interval through the ring thickness and the rounded corner at the end can be established at the same time.

• When showBaseLayer=true, the bottom layer of the same color 4% transparency occupies the place sector, which is not drawn by default and does not participate in the motion; the real filling layer is played above it.

• The top layer uses the complete sector path as the transparent hit layer to ensure the stability of the interaction range of hover/focus.

2.3 Color ability

• The default color order is Primary, Purple, Cyan, Mint, Green, Indigo, Blue, Yellow, Orange and Red.

• Each sector can define the color separately through data[i].color; sectors with undefined colors continue to use the default color sequence.

• colors can be used as the whole set of color palettes to override the entrance, and allow the array item to be undefined, and the empty item will revert the current colorMode corresponding color.

• Support Chart's general three color modes: sequence default color sequence, monochromeFade monochrome fade, monochrome monochrome. All three modes support data[i].color and colors[i] specified sector custom colors.

• color supports ordinary colors, CSS variables, linear-gradient(...) Strings and gradient objects.

• Background tool class names such as .bg-gradient-blue are not directly supported; the SVG sector uses fill, and the background / background-image of the background class will not be consumed by path.

2.4 Dynamic ability

• Support the automatic playback of the visual port for the first time, which can be turned off by appearOnView.

• Support 8 starting directions: top / top-right / right / bottom-right / bottom / bottom-left / left / top-left.

• Support scroll bar timeline: After scrollAppearance is turned on, the scrolling distance is directly mapped to appearanceProgress.

• Support controlled timeline: After the external input of appearanceProgress, the component only renders according to the progress and does not play by itself.

• Support uncontrolled methods: replay() refill, resetAppearance() reset, reverseAppearance() reverse return.

• The filling layer and the transparency layer are started at the same time: the next sector can be started after the filling is completed, and the transparency completion continues independently without blocking the subsequent sectors.

• Support reverse timeline: When appearanceProgress returns from 1 to 0, the fill width and transparency are reversed according to the same formula.

2.5 Interaction and accessibility

• When hover / focus is in the current sector, the outer radius of the sector thickens outwards, the inner radius remains unchanged, and the sector does not shift.

• When hover / focus is in the current sector, the center label shows the percentage and name of the current item. The default percentage is above and the name is below.

• labelFormatter can customize the content of the central label, and supports disassembly into two lines with \n; the first line is rendered according to the numerical style, and the second line is rendered according to the name style.

• Direct sub-elements <Text as="segment-value" /> / <Text as="segment-name" /> Custom center label style template can be passed; the component will automatically write the real percentage and name of the current sector, and the default center label will not be rendered when any character sub-element appears.

• showCenterLabel={false} can turn off the central label and the content of the central label role written externally.

• The root uses role="group" and a locale-aware default accessible name ("Circular chart" in en-US); an explicit aria-label takes priority. The SVG keeps focusable segments exposed; each hit target uses role="button" and its own accessible name containing the business name and formatted percentage.

• The sector hit layer can get the keyboard focus, and the focus behavior is consistent with the hover; the center tag uses aria-live="polite".

2.6 Frame Integration

• The root layer uses Frame; loading retains the declaration size and central content, fixes the sector at the starting point of the motion and suspends the interaction. The root layer of the chart explicitly closes Skeleton, and also reads the loading context of the upper Frame.

• Support enableResponsive, enableContext, enableScaleObserver, enableDefaultMotion transmitted to Frame.

• class, style and other undeclared attributes will be transmitted to the root Frame.

• The size of the chart is determined by the SVG geometric algorithm, which is expressed as Hug as an external layout sub-item.

3.1 Props

The rest of the undeclared attributes will be passed to the root layer Frame.

3.2 Component method

3.3 Data structure

interface CircularChartItem {  name: string;  value: number;  color?: CircularChartColor;  percentFormat?: NumberFormatOptions;}

Percentage number format priority: labelFormatter (center label) → item.percentFormat → component percentFormat → NumberFormatContext → NumberFormats default value. Sector hit layer aria-label does not use labelFormatter, but consumes percentFormat.

value <= 0 or non-numeric items will be filtered; empty charts are rendered when explicit empty arrays or all are invalid, and data is omitted to use the built-in sample data.

type CircularChartColor = string | CircularChartGradient; interface CircularChartGradient {  type?: "linear";  angle?: number;  stops: (string | { color: string; offset?: number | string; opacity?: number })[];}

Color priority: data[i].color → colors[i] → colorMode corresponds to the back color. Sectors with undefined colors will not be affected by other sector custom colors, and the current color mode will continue to be used. The gradient string supports the form of linear-gradient(135deg, #111111 0%, #6BE6D3 100%); the gradient object supports explicit declaration with angle and stops.

Layout model

Main layout model: internal atomic layout.

• The root layer is Frame, and the internal chart body uniformly carries the SVG drawing area and the center label, and is responsible for the equal scaling; HoverPanel is side by side with the chart body to maintain the original size.

• The size of the chart is determined by the size and SVG geometric algorithms; it is expressed as Hug as an external layout sub-item.

• It does not access the three-slot protocol and does not undertake the arrangement of general sub-elements.

For details, please refer to LayoutProtocol.md §12.3 (source code reference: specs/maintainers/LayoutProtocol.md).

Motion

6.1 The starting direction of the motion

startDirection supports 8 directions: top / top-right / right / bottom-right / bottom / bottom-left / left / top-left.

Judgment rules:

1. Emit rays from the center of the circle to startDirection.

2. Find the sector that the ray hits.

3. No matter where the ray falls in the sector, the motion starts from the starting boundary of the sector itself.

4. Then fill in sector by sector in a clockwise direction until all sectors are completed.

Usage examples

<CircularChart  data={[    { name: "Search Engine", value: 1048 },    { name: "Direct", value: 735 },    { name: "Email", value: 580 },    { name: "Union Ads", value: 484 },    { name: "Video Ads", value: 300 }  ]}/>

<CircularChart  size={320}  ringThickness={88}  cornerRadius={16}  separatorWidth={4}  hoverThicknessGrowth={4}/>

In the above example, cornerRadius={16} and separatorWidth={4} represent the design reference value under the 160x160 chart. When the actual size is 320, it is finally presented as a 32px rounded corner with an 8px interval.

<CircularChart  size={220}  ringThickness={64}  data={[    {      name: "Primary Gradient",      value: 42,      color: "linear-gradient(135deg, var(--primary, #111111) 0%, var(--secondary-mint, #6BE6D3) 100%)"    },    { name: "Default Purple", value: 30 },    {      name: "Object Gradient",      value: 18,      color: {        angle: 45,        stops: [          "var(--secondary-purple, #B899EB) 0%",          "var(--secondary-cyan, #A0BCE8) 100%"        ]      }    },    { name: "Default Mint", value: 10 }  ]}/>

<CircularChart  data={[    { name: "Direct", value: 735 },    { name: "Email", value: 580 }  ]}>  <Text as="segment-value" class="text-18 font-bold text-black-100" />  <Text as="segment-name" class="text-14 text-black-40" /></CircularChart>

<CircularChart  bind:this={chart}  startDirection="left"  appearOnView={false}/> <Button onclick={() => chart.replay()}>Replay fill</Button><Button onclick={() => chart.reverseAppearance()}>Reverse appearance</Button>

 <CircularChart  size={220}  ringThickness={140}  cornerRadius={8}  separatorWidth={3}/>