ChartGroup

Coordinate multiple charts in one area with shared category hover, layered rendering, and aligned axes.

We are building SnowUI components into interfaces people can use directly in AI conversations. Conversational UI is still in development; this page demonstrates website usage. Supported chat platforms and component versions will be announced after verification. Generating and using SnowUI interfaces inside AI conversations is completely free. It is not a project, uses no project or developer-seat quota, and requires no SnowUI registration, activation, or paid proof.

How to use

Use ChartGroup to combine charts under shared settings. Configure each chart through its own public data and visual APIs; do not modify internal marks from a page selector.

ChartGroup supplies shared axes and interactions. It does not create charts, titles, or legends.
Compose BarChart and LineChart explicitly, coordinating their width, height, and positioning to share a canvas.
The default root accessible name follows LocaleProvider through chartGroup.name; an explicit aria-label takes priority. The data-cell group uses chartGroup.cells. When no corresponding xLabels entry is provided, chartGroup.cell uses the complete {{index}} template with one-based numbering; explicit category names remain unchanged. Business names, data values, and numeric formatting remain controlled by the caller.

Import

import { ChartGroup } from '@snowui-design-system/components';

Usage

Shared category and HoverPanel

xLabels, xAxisMode and yMin/yMax align stacked weekly downloads with a target line. One anchor-top HoverPanel shows both charts.

Shared categories and label density

xMaxLabelCount controls monthly label density while both lines share the same categories and HoverPanel. showYAxis hides the vertical scale; solid and dashed series compare product traffic.

Individual point interaction

hoverMode="item" and showHitLayer={false} let each series respond independently to pointer or keyboard focus. Values show reading time in minutes.

Controlled category selection

activeCellIndex and onCellHoverChange connect the month buttons to chart hover. The surface HoverPanel stays pinned to the top right; values count projects in hundreds.

Default category and shared labels

defaultActiveCellIndex selects a category on load. showHoverLabel and alwaysShowHoverLabel display shared values; plotBounds reserves top space. adaptiveContrast keeps black-and-white marks and labels legible across light and dark surfaces.

Loading and empty state

loading keeps the final chart frame and axes while the series stays at its appearance start state. Switch to empty data to preview the coordinate frame before website visits are available.

API Reference

Property	Type	Default	Example	Description
`width`	`number \| string`	`800`	`width="Example"`	Root canvas width. Numbers become pixel CSS lengths; strings may use percentages or other CSS lengths. Shared hit regions and panels use the measured final size. Set width on child charts too, usually 100% when layered.
`height`	`number \| string`	`400`	`height="Example"`	Root canvas height as a number or CSS length. Percentage height needs a definite parent height. Child charts still need their own height; layered children without an X axis should subtract the one visible X axis’s 24px.
`xLabels`	`string[]`	`[]`	`xLabels={xLabels}`	Full category labels in shared activeCellIndex order, also the fallback for children without xLabels. Label culling does not remove entries or hit cells. An empty array still retains one fallback hit cell.
`yMin`	`number`	`—`	`yMin={42}`	Default lower Y bound for children. Without it, each child calculates its own domain. Set common bounds for a combined chart; ChartGroup does not aggregate child data domains. Explicit child values take priority.
`yMax`	`number`	`—`	`yMax={42}`	Default upper Y bound for children. Without it, each child derives its own maximum and scales may differ. Set one upper bound for comparable units. Explicit child values take priority.
`yTicks`	`number[]`	`—`	`yTicks={yTicks}`	Explicit Y tick values passed to children instead of automatic ticks. Visible labels may still be culled. Explicit child yTicks takes priority.
`yTickCount`	`number`	`6`	`yTickCount={42}`	Target count for automatic Y ticks, not an exact guarantee. Child domain, nice steps, and label culling determine actual ticks. Explicit yTicks takes priority.
`yTickFormatter`	`(value: number) => string`	`—`	`yTickFormatter={(value) => { /* handle value */ }}`	Format each Y tick for display without changing numeric values, domain, or hover values. Explicit child formatters take priority; otherwise each child uses its default.
`showXAxis`	`boolean`	`true`	`showXAxis`	Default visibility of X axis line and labels for children; ChartGroup draws no axis itself. In a layered chart, enable the X axis on only one child.
`showYAxis`	`boolean`	`false`	`showYAxis`	Default Y label visibility for children and an input to group top safe-area calculation. Explicit child values take priority. Each child measures its own side space; ChartGroup does not align different Y label widths.
`showGrid`	`boolean`	`false`	`showGrid`	Default grid visibility for children. A child draws lines at visible Y ticks; layered charts should retain one grid owner. Explicit child values take priority.
`showGuides`	`boolean`	`false`	`showGuides`	Default guide-line switch. LineChart can draw data-point guides; BarChart currently has no additional guide graphic. Explicit child settings take priority.
`xAxisMode`	`ChartGroupXAxisMode`	`"edge"`	`xAxisMode={value}`	LineChart point model: edge places first and last points at plot ends; cell centers points in category cells. Use cell for a line over BarChart. Shared group hit regions always use category cells.
`xLabelAutoCull`	`boolean`	`true`	`xLabelAutoCull`	Default automatic X label culling based on measured child text and available width. It hides labels without removing data, paths, cells, or shared indices. Explicit child values take priority.
`xMaxLabelCount`	`number`	`—`	`xMaxLabelCount={42}`	Default maximum visible X label count. Children may show fewer when space is short; full categories and hover data remain. Explicit child values take priority.
`yLabelAutoCull`	`boolean`	`true`	`yLabelAutoCull`	Default automatic Y label culling when space is short. Each child handles its own layout. Explicit child values take priority.
`yMaxLabelCount`	`number`	`—`	`yMaxLabelCount={42}`	Default maximum visible Y label count. Without yTicks, it also informs each child’s automatic tick count. Explicit child values take priority.
`plotBounds`	`ChartGroupPlotBounds`	`{}`	`plotBounds={value}`	Plot inset from the root canvas with numeric pixel top, right, bottom, and left fields. Shared hit and panel bounds use it. top can only increase the maximum child safe area; other edges do not change child geometry. Set bottom: 0 when all X axes are off.
`hoverMode`	`ChartGroupHoverMode`	`"cell"`	`hoverMode={value}`	cell coordinates one category hover across children. item leaves child hit handling in place without a group cell hit layer. It is also the child hoverMode fallback; explicit child values take priority.
`activeCellIndex`	`number \| null`	`—`	`activeCellIndex={42}`	Controlled zero-based category index from xLabels. null means none; undefined uses internal uncontrolled state. Not bindable: controlled callers write the next value from onCellHoverChange.
`defaultActiveCellIndex`	`number \| null`	`null`	`defaultActiveCellIndex={42}`	Initial uncontrolled category index only; later changes do not reset state. Ignored when activeCellIndex is defined. null starts without an active item.
`onCellHoverChange`	`(index: number \| null) => void`	`—`	`onCellHoverChange={(value) => { /* handle value */ }}`	Receives a new index or null after shared hover changes through pointer, cell focus, or child interactions. Internal interactions clamp finite values to valid categories. In controlled mode it only notifies; return values do not cancel updates.
`showHitLayer`	`boolean`	`true`	`showHitLayer`	Show the group SVG category hit layer only when hoverMode=cell and showHoverPanel=false. With a shared panel, root pointer coordinates and child hits take over. false does not disable child interaction.
`adaptiveContrast`	`boolean`	`true`	`adaptiveContrast`	Adaptive black-and-white contrast based on a solid host background and overlapping bars at the same origin. It adjusts black value text, default black-and-white nodes, and black lines, not colored series or nodes. The sRGB grayscale threshold is 0.5 and follows bar shape and opacity; background images and cross-chart coordinate transforms are unsupported. On by default; explicit child values take priority.
`showHoverPanel`	`boolean`	`true`	`showHoverPanel`	Combine child reports into one shared panel. In cell mode, root pointer position updates the category. On by default. When off, children may show their own panels through child settings. Numeric labels can coexist or be controlled with showHoverLabel. Empty data shows no panel.
`showHoverLabel`	`boolean`	`—`	`showHoverLabel`	Control child numeric hover labels. When omitted, follow child settings and derive a default from shared panel visibility. Explicit true or false takes priority over child settings; true permits labels alongside the shared panel.
`alwaysShowHoverLabel`	`boolean`	`false`	`alwaysShowHoverLabel`	Enable persistent child numeric labels. Merged by logical OR with child alwaysShowHoverLabel, so group false does not turn off a child’s explicit true. Final showHoverLabel still controls visibility.
`hoverPanelVariant`	`ChartHoverPanelVariant`	`"light"`	`hoverPanelVariant={value}`	Appearance of the one shared panel: light, dark, or blurred surface. Does not recolor bars, lines, or child numeric labels.
`hoverPanelPlacement`	`ChartHoverPanelPlacement`	`"pointer"`	`hoverPanelPlacement={value}`	Position the shared panel beside its data mark (anchor-side), at the highest data anchor (anchor-top), by the pointer, or at a plot corner with pin-*. ChartHoverPanel handles collisions.
`showHoverPanelLabel`	`boolean`	`false`	`showHoverPanelLabel`	Show the active category at the top of the shared panel. Read xLabels first, then fall back to the first child panel label.
`children`	`Snippet`	`—`	`<ChartGroup>Content</ChartGroup>`	Parameterless Snippet composing child charts explicitly. ChartGroup does not generate BarChart, LineChart, titles, or legends. Set each child’s width, height, and root positioning to share a canvas.
`class`	`string`	`""`	`class="my-component"`	Additional class merged with the root Frame class; not forwarded to child charts.
`style`	`string`	`""`	`style="width: 100%;"`	Additional inline style on the root Frame after canvas-size variable declarations. Useful for host positioning; not forwarded into child charts.
`enableResponsive`	`boolean`	`true`	`enableResponsive`	Enable root Frame responsive behavior. Chart canvas measurement is independent of this switch; percentage width and height do not require it.
`enableContext`	`boolean`	`true`	`enableContext`	Enable general root Frame context. It does not disable ChartGroup’s shared category, axis, or hover protocol for children.
`enableScaleObserver`	`boolean`	`false`	`enableScaleObserver`	Compatibility switch for root Frame scale observation, off by default. It does not control the chart’s own measured-size listener.
`enableDefaultMotion`	`boolean`	`true`	`enableDefaultMotion`	Enable root Frame default motion. It does not enable or disable child appearance motion as a group; each child uses its own public motion Props and instance methods.