Recharts Wrapper Implementations

Relevant source files

The following files were used as context for generating this wiki page:

• src/charts/Charts.tsx
• src/charts/ChartFrame.tsx
• src/charts/animation.ts
• src/charts/useChartAnimation.ts
• README.md
• src/index.ts

The HX-UI project implements a specialized wrapper layer over Recharts 3 to provide consistent styling, responsive behavior, and optimized data animations. These implementations ensure that charts align with the project's design language by utilizing CSS tokens for theming and custom tooltip components.

The library distinguishes between "initial loading" and "incremental updates" to prevent visual glitches common in streaming data visualizations. This is achieved through a custom animation system that controls how data points are matched during updates.

Sources: README.md:46-49, src/charts/ChartFrame.tsx:7-25

Architecture and Core Components

The chart system consists of structural wrappers, theme constants, and high-level component implementations.

Structural Wrappers

• ChartFrame: Wraps charts in a ResponsiveContainer. It manages the container height while allowing the width to follow the parent element to prevent layout breakage.
• ChartChrome: A convenience component that bundles CartesianGrid, XAxis, YAxis, and Tooltip with pre-configured project styles.

Component Hierarchy

The diagram shows how high-level Hx charts utilize internal frames, layout helpers, and animation logic to render data.

Sources: src/charts/ChartFrame.tsx:128-150, src/charts/Charts.tsx:49-65

Theming and Visual Styles

Charts utilize a centralized CHART_THEME object that maps Recharts properties to CSS variables defined in tokens.css. This ensures charts automatically update when the application switches between light and dark modes.

Theme Property	Mapping / Value	Description
grid	color-mix(in srgb, var(--border) 70%, transparent)	Muted grid lines
axis	var(--muted-foreground)	Label and tick text color
axisLine	var(--border)	Axis line color
series	[var(--primary), var(--segment-2), ...]	Defined color sequence for data series

Sources: src/charts/ChartFrame.tsx:28-40, src/tokens.css:32-38

ChartTooltip

The ChartTooltip replaces the default Recharts tooltip with a custom UI featuring rounded corners, borders, and a glass effect (backdrop-blur). It aligns multiple series values into a vertical column for improved readability and uses seriesColor(index) to match indicators with data lines.

Sources: src/charts/ChartFrame.tsx:64-96

Animation Strategy

HX-UI implements a custom animation logic to solve the "shaking" effect in real-time charts. Recharts' default matchByIndex strategy stretches points proportionally when data length changes; HX-UI uses matchAppend or matchByDataKey to keep existing points stationary while new points fade in.

Animation Flow Logic

This flow illustrates how the system selects an animation strategy based on data volume and render state.

Sources: src/charts/animation.ts:10-27, src/charts/useChartAnimation.ts:31-50

Configuration Options

The ChartAnimationOptions interface allows developers to customize animation behavior.

• match: Defines the matching mode (index, append, or { dataKey: string }).
• duration: The animation length in milliseconds (default: 320ms).
• easing: The timing function (default: ease-out).
• disabled: Manually disables animation, or automatically triggers if data exceeds ANIMATION_POINT_LIMIT (800 points).

Sources: src/charts/animation.ts:43-58

Standard Chart Components

The library provides high-level wrappers for common chart types, each pre-configured with HX-UI's theme and animation hook.

Component	Base Recharts Component	Key Features
HxLineChart	LineChart	Supports curved/linear lines and dot toggling.
HxAreaChart	AreaChart	Features vertical gradients (linearGradient) for fills.
HxBarChart	BarChart	Restricts radius to top corners only.
HxPieChart	PieChart	Supports donut shapes via innerRadius and legend formatting.
HxRadarChart	RadarChart	Uses PolarGrid and PolarAngleAxis.
HxRadialChart	RadialBarChart	Progress-ring style with percentage scaling via max prop.

Sources: src/charts/Charts.tsx:1-300

Implementation Example: Line Chart

The following snippet demonstrates how the HxLineChart integrates the animation hook and standard axes:

// src/charts/Charts.tsx:58-86
export function HxLineChart<T extends Record<string, unknown>>({
  data,
  series,
  xKey = "name",
  height = 260,
  animation,
  className,
}: LineChartProps<T>): JSX.Element {
  const anim = useChartAnimation({ ...animation }, data.length);
  return (
    <div className={className} style={{ height }}>
      <ResponsiveContainer width="100%" height="100%">
        <LineChart data={data as T[]}>
          <CartesianGrid {...CHART_GRID} vertical={false} />
          <XAxis dataKey={xKey} {...CHART_AXIS} />
          <YAxis {...CHART_AXIS} width={44} />
          {series.map((s, i) => (
            <Line
              key={s.dataKey}
              stroke={s.color ?? seriesColor(i)}
              vectorEffect="non-scaling-stroke"
              {...anim}
            />
          ))}
        </LineChart>
      </ResponsiveContainer>
    </div>
  );
}

Sources: src/charts/Charts.tsx:58-86

Summary

The Recharts wrappers in HX-UI prioritize visual consistency and performance. By abstracting the complex configuration of responsiveness and custom animation matching, the library provides a simplified API for developers to render themed, stable charts suitable for both static reporting and real-time monitoring.

Sources: README.md:46-49, src/charts/ChartFrame.tsx:7-25