Victory Native XL

Victory Native (XL) is a high-performance rewrite of the original Victory Native. It is designed to provide flexibility and ease of use while maintaining high frame rates for data visualizations on mobile devices.

Unlike the original version which relied on SVG, Victory Native (XL) is built on a modern graphics stack to ensure smooth animations (targeting 100+ FPS) even on low-end devices.

The CartesianChart component is the core component of victory-native. It serves two primary responsibilities:

1. Data Ingestion: It accepts raw data and configuration options (such as axis settings).
2. Data Transformation: It transforms raw data into a structured format that can be consumed by other victory-native components (like Line) via a render function.

To use it, you provide your data, specify which keys represent the x-axis and y-axes, and then use the render function to draw your chart elements based on the transformed data points.

<CartesianChart
  data={DATA}
  xKey="day"
  yKeys={["lowTmp", "highTmp"]}
  axisOptions={{ font }}
>
  {({ points }) => (
    <Line points={points.highTmp} color="red" strokeWidth={3} />
  )}
</CartesianChart>

If you are rendering a horizontal stacked bar chart using CartesianChart orientation="horizontal", you should use the useHorizontalStackedBarPaths hook instead of useStackedBarPaths.

Its arguments are identical to useStackedBarPaths, but the barOptions callback provides horizontal-specific orientation fields: isLeft and isRight instead of isBottom and isTop.

When using HorizontalBar within a CartesianChart with orientation="horizontal", the coordinate system and chartPressState values map as follows:

Coordinate Mapping

• points[key].x: The value endpoint on screen (horizontal position).
• points[key].y: The category center on screen (vertical position).
• points[key].xValue: The raw category value.
• points[key].yValue: The raw numeric value.

chartPressState Mapping

When interacting with the chart, the press state preserves semantic names:

• state.x.value.value: The raw category from xKey.
• state.x.position.value: The category's vertical screen position.
• state.y[key].value.value: The numeric series value.
• state.y[key].position.value: The value's horizontal screen position.

The Candlestick component integrates with the CartesianChart press model. When a user touches the chart, the nearest x value is selected, and the press state exposes the corresponding OHLC values. This allows for mobile-friendly scrubbing without requiring the user to touch the candle body exactly.

Available properties on the press state:

• state.matchedIndex.value
• state.x.value.value
• state.x.position.value
• state.y.open.value.value
• state.y.high.value.value
• state.y.low.value.value
• state.y.close.value.value

Axis Label Formatting

• Multiline Labels: Formatters can return newline-delimited strings (e.g., "Jan\n2024"). Layout measurement uses the widest line and total line height to reserve space.
• Hiding Labels: Returning an empty string "" from formatXLabel or formatYLabel hides the label and prevents it from reserving fallback or offset space.

Tick Configuration

• Downsampling: When tickValues are combined with tickCount, the tick values are downsampled to the requested count.
• Disabling Ticks: Passing tickCount={0} renders no ticks or tick labels, even if explicit tickValues are provided.

Victory Native (XL) leverages several high-performance libraries to handle rendering, animations, and gestures:

• React Native Skia: Provides the Skia rendering engine (the same engine used in Google Chrome) for sophisticated and performant graphics.
• React Native Reanimated (v3): Handles high-performance UI animations.
• React Native Gesture Handler (v2): Provides performant ways to handle user gestures.
• D3: Used for mathematical and data-driven logic.

The connectMissingData prop controls how the Area component behaves when the dataset contains gaps:

• connectMissingData={true}: The path is interpolated, resulting in a single, continuous area chart.
• connectMissingData={false}: The path will be broken into multiple disconnected segments at the locations of missing data values.

By default, Pie.Chart renders a simple <Pie.Slice /> for every data point. However, you can provide a children render function to customize the rendering of each slice. This allows you to inject components like <Pie.Slice />, <Pie.Label />, <Pie.SliceAngularInsets />, or <LinearGradient /> for each segment.

The render function receives an object containing a slice property of type PieSliceData, which provides the calculated geometry and data for that specific segment.

The ref prop on CartesianChart requires React 19 or newer to support passing a ref as a regular prop to function components.

If you are using React 18 or earlier:

• Use the deprecated actionsRef prop for programmatic interactions.
• Note that direct Canvas access via ref.canvas is not available without React 19.