LineChart 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 data trends as lines, with multiple series, area fills, solid or dashed strokes, axes, grids, and point markers.

When to use it

Use it for continuous values or trends over time. Use BarChart to compare categories. Configure points, axes, labels, and colors through the public chart API.

• Pass data through series. The component does not invent sample data; xLabels should match the data points.

• Loading reserves the axis and canvas, and waits for the end to display the data; HoverPanel is turned on by default, and the color and format are publicly configured using the chart.

• The default root accessible name follows LocaleProvider through lineChart.name; an explicit aria-label takes priority. The data-cell group uses lineChart.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 { Frame } from '@snowui-design-system/components';	import { LineChart } from '@snowui-design-system/components';</script> <LineChart series={[{ name: 'Component pages', data: [1280, 1460, 1390, 1720, 1880, 2140, 2360], color: 'Primary', strokeWidth: 3 }, { name: 'Quick Start', data: [620, 710, 680, 840, 920, 1040, 1180], color: 'var(--secondary-purple)', strokeStyle: 'dashed' }]} xLabels={['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']} width="100%" height={280} yTicks={[0, 500, 1000, 1500, 2000, 2500]} yTickFormatter={(value) => value < 1000 ? String(value) : `${value / 1000}K`} showYAxis showGrid showHoverPanel hoverPanelVariant="surface" />

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

• Atomic chart component: LineChart renders only the chart body. It does not include a title, card background, legend, or toolbar.

• No built-in sample data: LineChart does not simulate business data within the component; examples, business pages or outer combination components must be explicitly passed into series and xLabels.

• Area is a series option: Enable a fill with series[].area; there is no separate AreaChart component.

• Multiple series: One chart can mix solid and dashed lines, default ChartSpec color order, and different marker strategies.

• Built-in axes: X and Y axes and grid lines are part of LineChart.

• 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. When the label is widened, the drawing area is only compressed according to the actual increased width.

• Dynamic top safe area: The maximum visible edge distance of the line or marker is at least 8px on the top of the component; at least 16px when the Y axis is displayed. The top value label does not add an additional safe area, and remains at 4px above the node. If necessary, it can overflow the top edge of the drawing area; the safe area of the marker radius does not depend on whether the numerical label is displayed. When the X-axis is displayed, only 8px label spacing and 16px label height are retained at the bottom.

• Classification axis point model: The horizontal coordinates use the edge mode by default, and the first and tail data points and the first and last label centers are aligned with both ends of the drawing area; it can also be switched to cell mode to make the node located in the center of the equal-width classification cell. When the label cannot be put down, it is recalculated according to the current point mode and automatically reduces the intermediate coordinates and data points, and at least the beginning and end are retained.

• Configurable markers: Configure markers for a series or one point. Point-level settings take precedence.

• Hover label: The default hover / focus node displays the numerical label 4px above the point, and does not change the position by touching the top edge of the drawing area; at the same time, the node reverses the color and displays a 0.5px black vertical line behind the node. Font size 12px, regular body, default Black/100%. The digital format consumes NumberFormats.md, and the default is non-integer to display 2 decimal places. alwaysShowHoverLabel can make the numerical label often appear.

• Rounded corner turning line: LineChart only keeps the rounded turning line; the main body maintains a straight line, and only generates a local rounded corner according to cornerRadius at the flection point, and it is a straight line when cornerRadius=0.

• Chart general dynamic effect: Each series's own drawing duration is fixed at 1000ms, which is consistent with CircularChart; the line and Area are revealed from left to right. Multiple seriess are started in order according to the delay of 360ms, and each series has an independent slow-out timeline; the marker appears immediately when the line reveals to the corresponding point, and does not slow down the transparency.

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 LineChartColor = ChartColor;type LineChartStrokeStyle = "solid" | "dashed";type LineChartXAxisMode = "cell" | "edge"; interface LineChartMarkerConfig {  size?: number | string;  color?: LineChartColor | "line";} interface LineChartPointMarkerConfig {  size?: number | string;} interface LineChartPoint {  label?: string;  value: number;  marker?: boolean | LineChartPointMarkerConfig;  valueFormat?: NumberFormatOptions;} interface LineChartSeries {  name: string;  data: (number | LineChartPoint)[];  color?: LineChartColor;  strokeWidth?: number | string;  strokeStyle?: LineChartStrokeStyle;  cornerRadius?: number | string;  markers?: boolean | LineChartMarkerConfig;  guides?: boolean;  area?: boolean;  valueFormat?: NumberFormatOptions;}

Number-format priority: labelFormatter → point.valueFormat → series.valueFormat → component valueFormat → NumberFormatContext → NumberFormats default.

Color priority: series[i].color → colors[i] → colorMode corresponds to the return color. The default series color order is consistent with ChartSpec. color can be used as the main color of the monochrome mode. After passing in, monochromeFade defaults from 100% uniformly to 20% of the last series of the color. monochrome defaults to all non-customized seriess to use this color; when color is not transmitted, monochromeFade defaults to Primary, and monochrome defaults to Black4. Color supports SnowUI symanic color, ordinary CSS color, CSS variable, linear-gradient(...) Strings and gradient objects.

Y-axis scale rules:

• When yMax / yTicks is not transmitted, the upper limit of the domain is equal to the actual maximum data value of series, and nice ticks is only generated to the last readable scale not higher than the value; the highest point can be higher than the last grid line.

• The positive data contains 0 as the starting point of the vertical axis by default; when there is a negative number, the minimum value of the data is used to participate in the calculation.

• The step length is taken according to 1 / 2 / 5 × 10^n, and the number of target scales is controlled by yTickCount.

• yMaxLabelCount will limit the number of vertical coordinate labels; when yTicks is not transmitted, it will be given priority to generate nice ticks with min(yTickCount, yMaxLabelCount), and when a large number of yTicks are transmitted, it will be diluted and displayed according to the number of steps.

• yMin / yMax can be used as a domain boundary prompt; yTicks has the highest priority when explicitly passed in.

• yMin / yMax will not clamp the out-of-range data to the boundary; the lines and Area beyond the domain will first generate visible fragments according to the Y domain, and the round end point will be retained at the boundary. The marker and guide will only be displayed when the point value is in the current Y domain.

• When showGrid && showXAxis, the total number of horizontal lines defaults to yTickCount=6, of which the bottom one is borne by the x-axis baseline to avoid duplicate drawing of the bottom line.

Area fill rules:

• area: true generates a vertical gradient when the series uses ordinary colors. The top opacity is 0.04 (4%), and the bottom gradient is 0 (fully transparent). When the series color explicitly uses CSS gradient or ChartGradient object, Area directly follows its color mark and transparency; two color marks of the same color and opaque can form a real color area.

• Area does not provide color, transparency, gradient or baseline configuration independent of the line; it affects the line and the area at the same time through the series color, and affects the baseline through the vertical axis domain.

• area is independent of strokeStyle and can be combined with "dotted line + translucent area filling".

Marker rules:

• Marker is turned off by default; when a node is needed, it is explicitly turned on through series[].markers or point.marker.

• markers: true uses the Figma Dot structure: the whole 8x8 is composed of two layers of the lower Black/100% circle and the upper White/100% circle; the lower circle is 8x8 and the upper circle is 4x4, using var(--black-100) and var(--white-100) respectively.

• markers.size and point.marker.size scale the marker proportionally.

• markers.color only replaces the lower black/100% in the design draft; any color can be transmitted, or "line" can be passed to follow the current line color.

• Single point point.marker is only allowed to change the size or close, and it is not allowed to define nodes of different colors on the same line.

• When marker hover / focus, the lower circle becomes White/100% (var(--white-100)), the upper circle becomes Black/100% (var(--black-100)), and a vertical line running through the drawing area is displayed behind the node; the vertical line is 0.5px thick, round head, Black/100%.

• Marker other structures, lower/upper ratio and hover vertical lines are not available for customization.

Line rules:

• LineChart only retains the rounded turning line, and the main body is a straight line segment. Only at the middle inflection point, the front and rear line segments are truncated according to cornerRadius and local rounded corners are generated.

• When cornerRadius=0, a rounded corner is not generated, which is shown as an ordinary straight line.

• strokeStyle="dashed" Use Figma stroke settings: dash 2, gap 4, round cap.

Layout model

Main layout model: internal atomic layout.

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

• The root layer directly observes the final display size and recalculates the SVG coordinates; width="100%" / height="100%" does not require the page to return the container size.

• The horizontal classification axis calculates the number of points according to max(x(xLabels.length, ...series.data.length); the cell mode node position is bounds.left + (plotWidth / count) * (index + 0.5), and the edge mode node position is bounds.left + (plotWidth / (count - 1)) * index, which is in the middle when single points.

• Each X-axis label occupies one point interval; text is centered and truncated to one line. The label area is 16px high.

• In edge mode, the center of the first and last label and the first and last data points are the same x coordinates, and the label cell allows it to extend to the outside of the drawing area.

• X-axis label automatic display rule: according to the actual measurement of the complete text width of the final font and the original data position of the current xAxisMode, the adjacent visible text is at least 4px apart. Thinning only reduces the label, and does not delete or rearrarge the data points, broken line paths, marker, guide and hit cell. The retention index must form an equal number of steps; if the first and last two complete labels still cannot be placed, all X labels will be hidden.

• Y-axis label thinning rule: When automatically generating the scale, give priority to generating the appropriate quantity through yTickCount / yMaxLabelCount; when yTicks is explicitly passed in or the vertical space is insufficient, the display label is reduced according to the rules of the beginning and end retention and equal steps, and the horizontal grid line follows the visible Y label.

• The distance from the top of the X-axis label cell to the bottom x-axis baseline is 8px.

• The top of the drawing area is calculated by the shared content perception rule: half of the line width or the current maximum marker radius is used as the upward overflow of the graphic; ordinary graphics maintain a safe distance of 8px, and the Y-axis top scale needs at least 16px. The top value label does not increase the value, continues to maintain the 4px above the node and can overflow the top edge of the drawing area; the overflow of the marker is always included, regardless of whether the label is displayed. When there is an X axis, bottom=24px only contains the above 8px spacing and 16px label height; when there is no X axis, bottom=0.

• 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 is not estimated with fixed bounds or the number of characters; the spacing between the right edge of the label and the starting point of the line segment in the drawing area is fixed to 12px. For example, when the formatter outputs 100000, the drawing area is only reduced according to the actual width added by the text than the short scale, and the fixed spacing remains unchanged.

• 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).

Accessibility integration with Frame

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

• Each marker uses an independent aria-label, and the content includes series names, horizontal coordinate labels and values.

• The inside of the marker contains a transparent hit circle, which ensures that the keyboard focus and mouse hit do not only depend on the radius of the visible dot.

• The marker visible layer does not take over the pointer events, and the white center, black outer circle and transparent hit circle are all triggered by the hit circle; the default hit area is not less than 16x16.

• hoverMode="cell" works independently or within ChartGroup. Each cell hit area spans the plot around its category point, and the marker responds to hover or focus within that cell.

• loading retains the complete canvas and coordinate structure, and only restores the fold line, area and marker to the starting point of the dynamic effect; the root Frame clearly closes Skeleton. Empty series={[]} can cooperate with xLabels, yMin, yMax to establish the final coordinates first.

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

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

Layers and dynamic effects

The SVG layer from bottom to top is:

1. defs: color gradient, Area gradient, series reveal clipPath.

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

3. Base layer: When showBaseLayer=true, draw the complete Area and the same color 4% placehold layer of the line path, do not participate in the dynamic effect; do not render by default.

4. Area layer: Real Area path, revealed from left to right according to the corresponding series clipPath.

5. Guide layer: the vertical auxiliary line of the node follows the progress of the corresponding series.

6. Series layer: the real line path is revealed from left to right according to the corresponding series clipPath.

7. Marker layer: point markers, hover guide lines, and transparent hit circles appear when the reveal reaches each point.

8. Axis label layer: horizontal and vertical coordinate text.

Appearance motion follows the shared chart API:

• The complete chart is displayed directly when appearMotion={false}.

• By default, it will play automatically after entering the viewport, and the playback order is in the order of the series array.

• Each series uses fillProgress and opacityProgress from appearance-timeline.ts.

• Each series draws for 1000ms, matching CircularChart.

• Series start 360ms apart by default; the first starts immediately.

• fillProgress controls the left-to-right reveal clip, using easeOut with power 6.

• opacityProgress controls the opacity of the line, area, and guide line with the same easing.

• Markers do not use opacityProgress; they appear as soon as the reveal reaches their X coordinate.

• The shared chart API supports controlled appearanceProgress, scroll timelines, and replay(), resetAppearance(), and reverseAppearance().