data | GaugeChartItem[] | DEFAULT_DATA | data={[{ name: 'Reviewed', value: 72 }, { name: 'Remaining', value: 28 }]} | Proportional items with required name and finite positive value, plus optional color and percentFormat. Invalid and nonpositive items are removed in input order before taking maxItems. Percentages divide by the visible item sum. Omitted data uses five demo items; an empty or wholly invalid array keeps final dimensions and renders an empty chart. |
width | number | string | 320 | width={320} | Overall width, preferably a positive number converted from design pixels to rem. String CSS lengths are passed through, but SVG geometry uses parseFloat without unit conversion; percentages, calc(), and CSS variables are unreliable for geometry. |
minWidth | number | string | `${SECTOR_CHART_MIN_WIDTH}px` | minWidth={100} | Minimum responsive display width. Numbers follow the same design-pixel-to-rem rule as width; strings are CSS lengths. Defaults to 40 CSS pixels. Set equal to width to prevent shrinking, or lower to permit it. Applies only with enableResponsive=true. |
height | number | string | 160 | height={160} | Overall height, preferably positive design pixels, usually half of width. It changes the center and available radius. Strings have the same geometry parsing limits as width. |
ringThickness | number | string | 32 | ringThickness={32} | Nonnegative design-pixel ring thickness. Inner radius is max(0, outer radius minus thickness); outer radius is max(1, min(width / 2, height) minus hoverThicknessGrowth minus 1). At the outer radius the shape becomes a solid half pie. Strings only have their numeric part parsed. |
cornerRadius | number | string | "auto" | "auto" | cornerRadius={8} | Segment end radius in nonnegative design pixels at a 320px reference width, scaled by width / 320. auto uses 4. Final curvature is limited by ring thickness and segment angle; 0 gives square ends. |
separatorWidth | number | string | "auto" | "auto" | separatorWidth={4} | Transparent segment gap in nonnegative design pixels at a 320px reference width, scaled by width / 320. auto uses 2; 0 removes gaps. Path geometry leaves the actual background visible. |
colors | (GaugeChartColor | undefined)[] | — | colors={['var(--secondary-green)', undefined, 'var(--secondary-purple)']} | Override colors by visible filtered index. Entries accept semantic or CSS colors, variables, linear-gradient strings, or gradient objects with type, angle, and stops. Undefined positions fall back to colorMode; item color wins over the palette. Background utility class names are unsupported. |
colorMode | GaugeChartColorMode | "sequence" | colorMode="monochromeFade" | sequence cycles Primary and nine Secondary colors. monochromeFade reduces one color evenly from 100% on the first item to 20% on the last (one item stays 100%). monochrome uses one color for all items. Item and palette overrides apply in every mode. |
color | GaugeChartColor | — | color="var(--secondary-purple)" | Override the fallback primary color for monochromeFade and monochrome ahead of monochromeColor or mutedMonochromeColor; sequence does not use it. Supports the same solid, semantic, and gradient formats as item color. |
monochromeColor | GaugeChartColor | "Primary" | monochromeColor="Primary" | Fallback primary color only for monochromeFade when color is absent. Supports solid colors and gradients. Opacity descends from 100% to 20%; item color and colors still win. |
mutedMonochromeColor | GaugeChartColor | "Black4" | mutedMonochromeColor="Black10" | Fallback only for monochrome when color is absent. The default Black4 is theme-adaptive and low contrast; segment fill opacity is not reduced further. Item color and colors still win. |
hoverThicknessGrowth | number | string | 4 | hoverThicknessGrowth={4} | Nonnegative design pixels added outward on hover or focus. Inner radius and center stay fixed. 0 disables geometry growth but keeps data hints. String values parse only their number and do not scale by width / 320. No hoverScaleSize alias exists. |
startDirection | StartDirection | "left" | startDirection="right" | left reveals from the left end toward the right; right reveals from the right end toward the left. Only reveal order and sweep direction change, not category arrangement. |
showBaseLayer | boolean | false | showBaseLayer={true} | Show a 4%-opacity layer in each segment’s final color and geometry. Off by default. It neither animates nor receives hits, and does not change actual segments or data. |
appearMotion | boolean | true | appearMotion | Enable the appearance animation. false shows complete fill immediately and disables replay and reverseAppearance, while leaving hover thickness feedback active. |
appearOnView | boolean | true | appearOnView | In uncontrolled mode, play once when the chosen anchor reaches a viewport line. Same-origin iframes use position in the outer same-origin page. false leaves playback to instance methods. appearanceProgress takes precedence; scrollAppearance uses a scroll timeline. |
appearanceProgress | number | — | appearanceProgress={0.65} | Controlled fill progress clamped to 0..1. Caller changes determine the view; automatic and instance playback cannot change it. appearMotion=false still shows full fill. External changes do not call onAppearanceProgressChange. |
defaultAppearanceProgress | number | 0 | defaultAppearanceProgress={0} | Initial uncontrolled progress clamped to 0..1 and read once. Later Prop changes do not reset motion; controlled appearanceProgress takes precedence. Default 0 is the unfilled outline state. |
appearanceDuration | number | — | appearanceDuration={1000} | Total duration in milliseconds for instance and automatic playback, default 1000 regardless of segment count. Nonpositive values jump to the end on the next animation frame. Does not change scroll or controlled progress mapping. |
appearAnchorId | string | — | appearAnchorId="report-section" | ID of the page anchor for appearance. Defaults to the chart root when omitted; an ID that does not exist does not fall back. Affects automatic appearance and scroll timeline, not chart position. |
appearAnchorPoint | AnchorPoint | "top" | appearAnchorPoint="center" | Anchor top, center, or bottom compared with the viewport trigger line; does not change segment drawing direction. |
appearViewportPoint | number | "top" | "center" | "bottom" | 0.7 | appearViewportPoint="center" | Viewport trigger line from 0..1 or top=0, center=0.5, bottom=1. Default 0.7 means 70% of viewport height. Together with appearAnchorPoint it sets the trigger or scroll start. |
scrollAppearance | boolean | { distance?: number | string } | false | scrollAppearance={{ distance: 320 }} | Enable a window-scroll-driven uncontrolled timeline. Same-origin iframes also respond to outer-page scrolling. An object may override distance. Progress advances after the anchor passes the trigger line and reverses on upward scroll. Nested ScrollArea is not observed. appearanceProgress or appearMotion=false takes precedence. |
scrollAppearanceDistance | number | string | 320 | scrollAppearanceDistance={320} | CSS-pixel distance for scroll progress from 0 to 1, as a number or numeric string, with minimum 1. scrollAppearance.distance takes precedence. Applies only with the scroll timeline; string units are not converted. |
onAppearanceProgressChange | (progress: number) => void | — | onAppearanceProgressChange={(progress) => revealPercent = Math.round(progress * 100)} | Receives internal progress writes from 0..1, including direct completion during initialization, automatic playback, instance methods, and scrolling. Initial default value itself does not notify; external appearanceProgress changes are not observed. Return values cannot cancel updates. |
maxItems | number | 10 | maxItems={10} | Keep the first N valid items without sorting or merging Other. Integer-clamped to 1..28; 0 or NaN falls back to 10. Percentages use retained items only. Aggregate small categories before passing more than 28; wholly invalid data renders an empty chart. |
showCenterLabel | boolean | true | showCenterLabel={false} | Show the center content region. false hides dynamic default labels, segment-value and segment-name templates, and static center-label; it does not disable an explicitly enabled HoverPanel. |
centerTitle | string | "" | centerTitle="Docs" | Center title without hover or focus, using the default value-row layout. Replaced by percent or the first labelFormatter line during interaction, then restored. An empty string takes no row. Hidden by showCenterLabel=false; static center-label takes precedence. |
centerSubtitle | string | "" | centerSubtitle="This week" | Center subtitle without hover or focus, using the default name-row layout. Replaced by the active item name or second labelFormatter line during interaction, then restored. May be set independently; it does not create HoverPanel data. |
hoverMode | ChartHoverMode | "cell" | hoverMode="item" | cell hits by angle across the ring, preserving the category through transparent gaps while excluding the center hole and outside. item only hits segment paths. Both modes retain keyboard focus hints. |
showHoverPanel | boolean | true | showHoverPanel={false} | Show a structured panel for the active hover or focus segment while retaining dynamic center labels. false disables it, except that a visible static center-label automatically enables a panel to carry segment information. |
hoverPanelVariant | ChartHoverPanelVariant | "light" | hoverPanelVariant="surface" | Panel appearance: light glass by default, dark glass, or theme surface. It does not change data or hit behavior. |
hoverPanelPlacement | ChartHoverPanelPlacement | "pointer" | hoverPanelPlacement="pin-top-right" | pointer follows the pointer. anchor-top and anchor-side position relative to the current pointer point, or chart center for keyboard focus. pin-* fixes to the named chart edge or center, keeps an 8px edge gap, and participates in viewport collision handling. |
showHoverPanelLabel | boolean | false | showHoverPanelLabel={true} | Show the active segment name above the panel data row. false shows only the row. Visible only with an active item and enabled panel. |
percentFormat | NumberFormatOptions | — | percentFormat={{ fractionDigits: 0, locale: "en-US" }} | Number format for center and panel percentages and segment aria-label. Supports fractionDigits, locale, and other NumberFormatOptions. Priority: item percentFormat, this Prop, NumberFormatContext, then the default one decimal. labelFormatter changes only center text. |
labelFormatter | (item: GaugeChartItem, percent: number) => string | — | labelFormatter={(item, percent) => Math.round(percent) + '%\n' + item.name} | On hover or focus, receives valid item and percent in 0..100 and returns center text. A newline splits at most two lines for value and name. Not called with static center-label or showCenterLabel=false; panel and segment aria-label percentages remain unchanged. |
loading | boolean | — | loading={true} | Waiting-for-data state. Keeps final width, height, and center content while holding segments at their appearance start and pausing interaction. When cleared, motion starts according to viewport conditions. Does not render Skeleton; also reads ancestor Frame loading context. Explicit data={[]} does not use demo data. |
children | Snippet | — | <GaugeChart><Text as="segment-value" /><Text as="segment-name" /></GaugeChart> | Parameterless center Snippet when showCenterLabel=true. Direct Text as="segment-value" or as="segment-name" children are dynamic label templates. Direct Frame as="center-label" stays visible and enables the panel. Static content does not inherit default center layout. Omit for default text; the center is display content, not a toolbar. |
class | string | "" | class="report-chart" | Additional class on the chart root Frame, empty when omitted. Styles the public root without penetrating internal SVG and label structure. |
style | string | "" | style="align-self: center;" | Additional inline style on the root Frame after component variables. Use for external layout; prefer width, height, and ringThickness for chart geometry. |
enableResponsive | boolean | true | enableResponsive={false} | Shrink the chart proportionally when its container is short of width, including in side-by-side flex layouts. minWidth sets the minimum, 40px by default; matching width prevents shrinkage. HoverPanel does not scale. false keeps declared dimensions. Also passed to Frame. |
enableContext | boolean | true | enableContext={false} | Forward the Frame context switch. Chart width, height, color, and appearance progress still use their own Props. |
enableScaleObserver | boolean | false | enableScaleObserver={false} | Forward the legacy Frame size-observer compatibility switch, off by default. It is not percentage chart sizing and is not recommended for new examples. |
enableDefaultMotion | boolean | true | enableDefaultMotion={false} | Forward Frame outer default motion. It does not own the chart appearance timeline or segment hover thickening, which use appearMotion or appearanceProgress and hoverThicknessGrowth respectively. |
