Chart Frames & Composition
Relevant source files
The following files were used as context for generating this wiki page:
Chart Frames & Composition provides a standardized wrapper system for Recharts 3 components within the HX-UI library. It ensures responsive behavior, unified thematic styling via CSS tokens, custom tooltip interaction, and specialized incremental animation logic.
The system encapsulates Recharts components to solve four primary issues: responsive width management, theme integration for axes and grids, high-fidelity tooltips matching the library UI, and smooth data updates for real-time monitoring.
Sources: src/charts/ChartFrame.tsx:7-24, README.md:46-51
Core Architecture
The chart system follows a layered approach where base design tokens inform the visual properties of high-level chart components.
ChartFrame Component
The ChartFrame serves as the outermost container. It utilizes ResponsiveContainer to ensure charts follow the width of their parent element. It requires a mandatory height prop because ResponsiveContainer only manages width automatically.
Sources: src/charts/ChartFrame.tsx:107-133
ChartChrome & UI Elements
ChartChrome is a utility component that bundles common Recharts sub-components including CartesianGrid, XAxis, YAxis, and the custom ChartTooltip. It ensures vertical grid lines are treated as noise by default (horizontal only) and applies unified axis styling.
Sources: src/charts/ChartFrame.tsx:156-189
Thematic Styling
Charts consume semantic colors from tokens.css. This prevents hardcoded hex values and allows charts to adapt automatically to light and dark modes.
| Property | Token / Variable | Description |
|---|---|---|
| Grid | var(--border) (70% mix) | Subtle grid lines for Cartesian charts. |
| Axis Text | var(--muted-foreground) | Label color for X and Y axes. |
| Axis Line | var(--border) | The stroke color for the axis itself. |
| Series 1 | var(--primary) | The default color for the first data series. |
| Series 2-5 | var(--segment-2) to var(--segment-5) | Sequential colors for multi-series charts. |
Sources: src/charts/ChartFrame.tsx:28-40, src/tokens.css:26-30
Series Color Logic
The seriesColor(index) function retrieves colors from the defined series sequence. If the number of data series exceeds the defined length (5), the function loops back to the beginning of the sequence.
Sources: src/charts/ChartFrame.tsx:43-45
Animation System
HX-UI distinguishes between "First Load" and "Incremental Updates." Standard Recharts behavior matches data by array index, which causes visual "stretching" or full-path redraws when data points are added.
Animation Match Modes
- Index: Matches by array index. Used for first renders or full batch replacements.
- Append: Matches sequentially; new items fade in while old items remain stationary. Ideal for logs or real-time monitoring.
- DataKey: Matches by a unique business ID (e.g.,
id). This allows points to slide smoothly to new positions during windowed data shifts.
Sources: src/charts/animation.ts:14-24, src/charts/animation.ts:68-80
Performance Constraints
Animation is automatically disabled if the data point count exceeds ANIMATION_POINT_LIMIT (default: 800) to prevent frame drops on low-end devices.
Sources: src/charts/animation.ts:40-45
Chart Components
The library provides several pre-composed chart types that integrate the frame, chrome, and animation logic.
Line and Area Charts
- HxLineChart: Supports curved (
monotone) or straight (linear) lines. Usesnon-scaling-stroketo prevent line distortion during responsive resizing. - HxAreaChart: Implements a vertical gradient fill (upper opaque to lower transparent) for each series.
Sources: src/charts/Charts.tsx:44-77, src/charts/Charts.tsx:93-138
Specialized Charts
- HxBarChart: Applies rounding only to the top corners of bars to prevent a "floating" appearance.
- HxPieChart: Includes a 2-pixel
paddingAngleto ensure sector boundaries are visible even with similar color hues. - HxRadialChart: Used for progress rings. It supports a
maxvalue to calculate percentage-based arc lengths.
Sources: src/charts/Charts.tsx:156-177, src/charts/Charts.tsx:206-224, src/charts/Charts.tsx:280-305
Custom Tooltip Design
The ChartTooltip replaces the default Recharts grey inline styles with a glass-effect panel (backdrop-blur).
The layout aligns values in a single column on the right side of the panel to improve readability when multiple series are present.
Sources: src/charts/ChartFrame.tsx:68-98
Summary
Chart Frames & Composition standardizes data visualization in the HX-UI ecosystem. By wrapping Recharts 3, it enforces consistent aesthetics through CSS tokens, improves performance via intelligent animation gating, and enhances usability with custom tooltips and responsive containers. Developers can either use pre-built components like HxLineChart or compose custom charts using ChartFrame and ChartChrome.