GaugeChart 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 several proportions in a semicircle or half-pie, with segments, gradients, ring thickness, and appearance motion.

When to use it

Use GaugeChart for semicircular proportional data. Like CircularChart, its current data model divides each value by the sum of items. Use Progress for task completion.

• At present, the component displays semi-ring proportional data, which is not a min/max single indicator instrument; each item of data uses name and positive value, and the proportion is calculated according to the sum of the valid display items.

• Omitting data will display sample data, and empty arrays will show empty diagrams; central copy and content will be configured with centerTitle, centerSubtitle or public role configuration.

• The default root accessible name follows LocaleProvider through gaugeChart.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 { GaugeChart } from '@snowui-design-system/components';	// Sample data for this week’s documentation review.	const channels = [	    { name: 'Ready', value: 72, color: 'var(--primary)' },	    { name: 'Review', value: 18, color: 'var(--secondary-purple)' },	    { name: 'Planned', value: 10, color: 'var(--secondary-orange)' }	];	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);">    <GaugeChart bind:this={trafficChart} data={channels} width={360} height={180} ringThickness={32}        centerTitle="Docs" centerSubtitle="This week" appearOnView defaultAppearanceProgress={0}        aria-label="Sample weekly documentation review" />    <div style="display: flex; align-items: center; justify-content: center; flex-wrap: wrap; gap: var(--gap-4) var(--gap-3);" aria-label="Review status legend">        {#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>        {/each}    </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 USE OF THE RUNNING PACKAGE AND THE DELIVERY OF THE ORIGINAL SOURCE CODE ARE EXECUTED ACCORDING TO LICENSE, AND THE PAID OPERATION RIGHTS AND INTERESTS ARE NO LONGER DIVIDED BY ADVANCED FUNCTIONS.

• Default 10 items, up to 28 items: Default maxItems=10. When explicitly increasing maxItems, up to 28 items are displayed. The color sequence is exactly the same as the CircularChart, and it still loops in order after 10 items.

• Color priority: data[i].color → colors[i] → colorMode corresponds to the fallback color. The single color only affects the current sector and will not be passed to the subsequent sector.

• Size benchmark: cornerRadius and separatorWidth both represent the design benchmark under the 320px wide instrument chart. The internal scale of the component is uniformly scaled according to width / 320, and both numbers and string numbers are understood according to the reference value.

• Transparent interval: The sector interval is generated by padAngle + padRadius in the path geometry stage, which runs through the inner and outer arcs and shows the real background; no fixed white stroke is drawn, and the back gap mask is not used.

• Layer structure: The base layer is controlled by showBaseLayer, which is closed by default, and the 4% placeholder layer is drawn when it is turned on; the fill layer is responsible for the real filling and motion; the hit layer uses the complete sector path to be responsible for hover / focus / aria.

• Hover emphasis: Each sector immediately turns from the current geometry to the latest hover/focus target, cancels the unfinished old animation, and does not replay the backlog; when hover/focus, the sector is not displaced, and only the outer radius slows down to increase hoverThicknessGrowth; the percentage is displayed above the center label, and the current item name is displayed below.

Shared pure logic is located at components/src/lib/chart/: color, gradient, geometric reference scaling, ring sector path and appearance timeline. GaugeChart itself retains the semicircle center, starting direction, center label and hover status management.

2.1 Props

Other undeclared attributes pass through to the root Frame. The root uses role="group" and a locale-aware default accessible name ("Gauge 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.

2.2 Method

2.3 Data structure

type GaugeChartColor = string | GaugeChartGradient; interface GaugeChartGradient {  type?: "linear";  angle?: number;  stops: (string | { color: string; offset?: number | string; opacity?: number })[];} interface GaugeChartItem {  name: string;  value: number;  color?: GaugeChartColor;  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. It is not supported to directly input background tool class names such as .bg-gradient-blue, because SVG path consumes fill.

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 width / height and SVG geometric algorithm; 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.

• The root layer explicitly inputs enableResponsive / enableContext / enableScaleObserver / enableDefaultMotion, and transmits class, style and undeclared attributes.

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

Motion

Usage examples

<GaugeChart centerTitle="Docs" centerSubtitle="This week"  data={[{ name: "Ready", value: 72 }, { name: "Review", value: 18 }, { name: "Plan", value: 10 }]} />

<GaugeChart  data={[    { name: "Primary", value: 32 },    { name: "Growth", value: 24 },    { name: "Support", value: 18 },    { name: "Explore", value: 14 },    { name: "Other", value: 12 }  ]}/>

<GaugeChart  colors={[undefined, "var(--secondary-blue)", "linear-gradient(135deg, var(--black-100) 0%, var(--secondary-blue) 100%)"]}  data={[    { name: "Done", value: 62, color: "var(--secondary-mint)" },    { name: "Doing", value: 24 },    { name: "Remain", value: 14 }  ]}/>

<script lang="ts">  let chart: { replay: () => void; reverseAppearance: () => void } | undefined;</script> <Button onclick={() => chart?.replay?.()}>Replay fill</Button><Button onclick={() => chart?.reverseAppearance?.()}>Reverse appearance</Button><GaugeChart bind:this={chart} startDirection="right" appearOnView={false} defaultAppearanceProgress={1} />

<GaugeChart  width={320}  height={160}  data={[    { name: "Growth", value: 24 },    { name: "Support", value: 18 }  ]}>  <Text as="segment-value" />  <Text as="segment-name" /></GaugeChart>