BarChart 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

Compare categorical data with horizontal, vertical, grouped, or stacked bars, axes, and interactive tooltips.

When to use it

Use BarChart to compare categories. Use LineChart for continuous trends and CircularChart for proportions. Configure axes and colors through the public chart API.

• Input business data; omitting data will display the built-in sample data. Mode controls single column, grouping, stacking and other forms. For specific structure, please refer to API and data structure.

• Loading retains the chart and suspends data interaction; HoverPanel is turned on by default. The color of the chart is configured by colors / colorMode.

• The default root accessible name follows LocaleProvider through barChart.name; an explicit aria-label takes priority. The data-cell group uses barChart.cells. 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 } from '@snowui-design-system/components';	import { BarChart } from '@snowui-design-system/components';	let monthlyCoverageChart: any;</script> <Frame column style="align-items: center; gap: var(--gap-5); width: 100%;">	<BarChart		bind:this={monthlyCoverageChart}		width="100%"		barWidth={32}		groupGap={4}		showYAxis		showGrid		hoverMode="cell"		showHoverLabel={true}		showHoverPanel={true}		alwaysShowHoverLabel={true}		hoverPanelPlacement="pointer"		hoverPanelVariant="dark"		data={[			{ name: 'Jan', value: 82.6 },			{ name: 'Feb', value: 84.1 },			{ name: 'Mar', value: 83.4 },			{ name: 'Apr', value: 85.7 },			{ name: 'May', value: 86.2 },			{ name: 'Jun', value: 84.9 },			{ name: 'Jul', value: 87.3 },			{ name: 'Aug', value: 86.8 },			{ name: 'Sep', value: 88.1 },			{ name: 'Oct', value: 87.6 },			{ name: 'Nov', value: 89.2 },			{ name: 'Dec', value: 88.7 }		]}	/>	<div style="display: flex; justify-content: center; gap: var(--gap-2); width: 100%;">		<Button onclick={() => monthlyCoverageChart?.replay?.()}>Replay animation</Button>		<Button onclick={() => monthlyCoverageChart?.reverseAppearance?.()}>Reverse animation</Button>	</div></Frame>

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

Design principle

• Chart Atomic Component: BarChart is only responsible for the body of the bar chart, and does not have built-in titles, card backgrounds, legends or toolbars.

• Unit model: A category is a bar unit. The unit uniformly controls the thickness, rounded corners, direction and category coordinates of the column; the unit can render single columns, multi-segment, overlapping columns or multiple parallel columns.

• Multi-segment unified rules: Three-segment is a special case of multi-segment. mode="stack" uses segments to render any number of segments; segmentGap={0} means that there is no interval in the middle, and segmentGap>0 means that there is a transparent interval between the segments and each segment has an independent rounded corner. The hover / focus / normal display value is only displayed once above the top segment, and the value is the sum of all segments.

• Overlapping rules: mode="overlay" uses the first two valid data of bars, the first is the back layer and the second is the front layer; the two layers are named and valued independently, and the zero baseline is coaxially superimposed without accumulation. The back layer is 10% opacity and the front layer is 100%; the front layer can be higher than the back layer.

• Side-by-side bars: mode="group" uses bars to place bars beside each other within a category. The default gap is barGap=4; colors follow Chart’s default sequence, and the group can have more than two bars.

• Direction rule: orientation="vertical" is a vertical bar chart, and the category axis is horizontal; orientation="horizontal" is a horizontal bar chart, and the category axis is vertical. All column modes support two directions.

• The coordinate axis is built-in: The coordinate axis, scale and grid line belong to the BarChart morphological ability and are placed in the component.

• Responsive density: BarChart directly observes the final display size of the root layer and recalculates SVG geometry with the actual measured width and height, without requiring the page to create ResizeObserver by itself. The column thickness can be narrowed with the category cell, but not less than 2px; the visual spacing of side-to-side columns and adjacent category columns in the same category should not be less than 4px.

• Horizontal density: The height of the horizontal column follows the lower limit of the column thickness 2px, and the spacing of the upper and lower adjacent columns is 4px; the category Y label is diluted according to the height of the final drawing area, the height of the row of the 16px and the spacing of the upper and lower 4px, and all of them are hidden when the beginning and the end still cannot be put down.

• Label thinning: xLabelAutoCull only reduces the category axis label of the vertical map, and does not delete the column, coordinate axis, hit cell or data; the bottom value scale of the horizontal map is automatically thinned according to the actual width of the drawing area. The empty string label does not participate in the number of candidates and the first and last judgment, and the labels such as sparse months are diluted according to non-empty items. It can be seen that the label must be displayed completely and the adjacent text must keep at least 4px; when there is not enough space, keep the first and last non-empty items and dilute them step by step. If the first and last two complete labels still cannot be placed, all horizontal axis labels will be hidden. The permanent top value uses an independent valueLabelAutoCull / valueMaxLabelCount, which is diluted according to the text width of the final value; the omitted value will still be displayed when the corresponding column hover / focus.

• Y-axis adaptive width: The Y-axis does not use a fixed reserved width; the width of the label area is equal to the actual rendering width of the current widest visible label, and the right edge of the label and the starting point of the drawing area are fixed for 12px. The vertical value axis and the horizontal category axis use the same Chart to share the measurement entrance; when the label is widened, the drawing area is only compressed according to the actual increased width.

• Dynamic top safety zone: The top of the ordinary column spacing component is at least 8px; the minimum is 16px when the longitudinal map shows the Y axis; the top value label does not add an additional safe area, but still maintains 4px above the top of the column, and can overflow the top edge of the drawing area if necessary. When the X axis is displayed, only the 8px label spacing and 16px label height are retained at the bottom, and the bottom edge of the label is aligned with the bottom of the component; when the X axis is hidden, the drawing area extends to the bottom of the component.

• Hover rule: The column hover uses the overlay mechanism of StyleSpec.md §2.4 and does not rewrite the color of the column itself. Solid columns with visual transparency of 40% or more are superimposed on StaticWhite/20% according to the filled Button hover rule; light transparent columns with visual transparency of less than 40% are superimposed on Black/4% according to the light black hover gear. overlay The back 10% and the multi-sepment light section will follow Black/4% overlay.

• Hover label: The default hover / focus column displays the value label 4px above the column, and does not change the position by touching the top edge of the drawing area. Font size 12px, regular body, the default color is Black/100%. stack only shows the total value of the whole stacked column in the top section, and any segment of hover points to this total value; other modes still show the corresponding column value. The number format consumes NumberFormats.md, and the default is non-integer to display 2 decimal places. alwaysShowHoverLabel can make the value label appear often; when the motion is played, the label value changes in real time according to the current column height ratio, from 80% corresponding value to the complete value.

• hover panel: The label-to-row section keeps its existing 2px design baseline. 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.

• Appearance motion: All categories share one BarChart timeline. Bars start at 80% of their target height or width, then grow to 100% from left to right. Adjacent categories start in sequence.

2.1 Props

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

2.2 Component method

2.3 Data structure

type BarChartOrientation = "vertical" | "horizontal";type BarChartMode = "single" | "stack" | "overlay" | "group"; interface BarChartSegment {  name?: string;  value: number;  color?: BarChartColor;  valueFormat?: NumberFormatOptions;} interface BarChartBar {  name?: string;  value: number;  color?: BarChartColor;  valueFormat?: NumberFormatOptions;} interface BarChartItem {  name: string;  value?: number;  color?: BarChartColor;  valueFormat?: NumberFormatOptions;  segments?: BarChartSegment[];  bars?: BarChartBar[];  backgroundValue?: number;  backgroundName?: string;}

The recommended data of mode="overlay" is data[].bars, and two real data columns are passed into each category:

Legacy value/backgroundValue/backgroundName fields apply only when bars is absent. backgroundValue supplies the real back-layer value, named by backgroundName ?? name; value supplies the front-layer value, named by name. Without backgroundValue, render only the front layer; do not duplicate its value into a fictional back layer. New code should use bars. Other modes ignore backgroundValue/backgroundName.

<BarChart mode="overlay" data={[  { name: 'Organic search', bars: [{ name: 'Previous quarter', value: 8400 }, { name: 'Current quarter', value: 10200 }] },  { name: 'Direct traffic', bars: [{ name: 'Previous quarter', value: 7600 }, { name: 'Current quarter', value: 6800 }] },  { name: 'Referrals', bars: [{ name: 'Previous quarter', value: 4200 }, { name: 'Current quarter', value: 5100 }] }]} />

Numerical format priority: labelFormatter → segment/bar.valueFormat → item.valueFormat → component valueFormat → NumberFormatContext → NumberFormats default value.

Color priority:

• single: data[i].color → colors[i] → colorMode。

• stack: segments[j].color → data[i].color → monochromeFade; use the transparency gradient of the same color when not customized.

• overlay: The back layer and the front layer use the same color by default, and the transparency of the back layer is fixed at 0.1.

• group: bars[j].color → data[i].color → colors[j] → colorMode。

Colors may be SnowUI semantic colors, CSS colors or variables, linear-gradient(...) strings, or gradient objects.

Layout model

Main layout model: internal atomic layout.

• The root layer is Frame, and the interior is a single SVG drawing area.

• The CSS size of the root layer is determined by width / height, and the SVG coordinate algorithm uses the final actual measurement size of the root layer; width="100%" can be directly Filled, and there is no need to transmit the pixel width back after the page listens to the container.

• At orientation="vertical", the category axis is a horizontal cell, and the column is located in the center of the cell; at orientation="horizontal", the category axis is a vertical cell.

• The width of the Y-axis label area is determined by the actual SVG rendering width of the widest text in the all-visible Y label, and does not use fixed bounds or character number estimation; the distance between the right edge of the label and the starting point of the drawing area is fixed to 12px.

• The automatic domain upper limit directly uses the current data maximum value; nice ticks only generates the last easy-to-read scale not higher than this value. The highest column can be higher than the last grid line, and the top is only controlled by the 8px / 16px content safe area. The explicit yMax or yTicks is not rewritten by this automatic rule.

• The top of the drawing area is calculated by the shared content perception rule: the ordinary column is 8px, and the vertical value Y axis is 16px; the maximum value of the two is taken. The value label does not increase the value, and continues to maintain the position of 4px above the top of the column. If necessary, it can overflow the top edge of the drawing area. The value label of the horizontal column is located on the right side of the column, and the top safety zone is also not added. When there is an X axis, bottom=24px only contains 8px label spacing and 16px label height; when there is no X axis, bottom=0.

• Internal rules of the unit:

  • single: One unit and one column.

  • stack: One unit has a multi-segment column; when segmentGap=0, the middle segment has no interval and only the rounded corners are kept at the beginning and end of the whole; when segmentGap>0, each segment has an independent rounded corner; the value label only belongs to the top segment, and the content is the sum of all segments.

  • overlay: Two-layer coaxial column of a unit, 10% of the back layer and 100% of the front layer.

  • group: Multiple side-by-stand columns in a unit, the thickness is uniform, and the color can be defined one by one.

• When the responsive narrowing, the column thickness is compressed to 2px first; the parallel column spacing of the same category and the column spacing of adjacent category are kept at least 4px. The horizontal coordinates and the permanent top values are diluted according to their own text needs, respectively, and the number of columns, data domain, hit cell and dynamic sequence are kept intact.

• 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.7 (source code reference: specs/maintainers/LayoutProtocol.md).

Barrier-free integration with Frame

• The root uses role="group" and a locale-aware default accessible name ("Bar chart" in en-US); an explicit aria-label takes priority. Interactive hit targets retain their independent semantics.

• Each column / each segment has an independent transparent hit layer, using role="button", tabindex="0" and aria-label containing names and values.

• Both standalone BarChart and charts inside ChartGroup support hoverMode="cell". Each cell covers the plot around its category center; all bars or segments in that category respond together.

• loading retains the complete canvas and coordinate structure, and only restores the column to the starting point of the motion; the root Frame clearly closes the Skeleton. The explicit empty data={[]} does not return the default demonstration data, and can cooperate with xLabels, yMin, yMax to establish the final coordinate first.

• The explicit input enableResponsive / enableContext / enableScaleObserver / enableDefaultMotion.

• class, style and undeclared attributes are transmitted to the root Frame.

Layers and motions

The SVG layer from bottom to top is:

1. defs: Color gradient.

2. Grid / axis layer: grid line and x axis baseline.

3. Base layer: When showBaseLayer=true, draw the final size placeholder bar, fill-opacity=0.04; do not render by default.

4. Series layer: real column.

5. Hit layer: complete hit area.

6. Axis label layer: X / Y axis text.

The motion API is consistent with ChartSpec.md §9. All columns share the same chart-level timeline, and the categorys are started in order; the side-by-side columns, stacked segments or overlapping layers inside the unit use the same local progress. The column appears in the form of height/width: the vertical column first shows 80% of the target height, and then fills it up to 100% from the top; the horizontal column first shows 80% of the target width, and then fills it to 100% to the right. The start-up interval of adjacent categorys is fixed; the whole timeline applies easeOut to slow down first; the duration of the unit elevation is gradually lengthened in the order of category, so that the unit to the right rises slower. In the stack mode, all segments in a category share the same local progress, so BC-02 / BC-03 will not have the rhythm of starting each segment separately; at any time, the bottom segment/middle segment/top segment will increase synchronously according to the same proportion of their respective target heights. segmentGap only acts on the boundary of adjacent segments, and maintains a fixed pixel value during the motion; when segmentGap=0, adjacent segments always fit without spacing. appearanceDuration can still cover the playback speed of the entire timeline. The value of the usual display or hover label is directly calculated by using the current column height ratio; stack uses the total value of the whole column to make up from the current ratio of the total value to the final total value.