CartesianChartHost

CartesianChartHost is the entry point for Cartesian charts. It accepts CartesianChart and CartesianChartModelProducer instances, facilitates communication between them, and displays the chart. It also handles scroll and zoom and shows a placeholder when no data is available.

CartesianChartHost(rememberCartesianChart(/* ... */), modelProducer, /* ... */)

You can also use a manually created CartesianChartModel instance instead of a model producer:

CartesianChartHost(rememberCartesianChart(/* ... */), model, /* ... */)

Sizing

The chartAreaHeight parameter sets the default height of the coordinate system. Its default value is 192 dp. Axis margins, legends, markers, and other components add to this height instead of being fitted inside it.

This default applies only when the host’s height isn’t otherwise constrained. Modifier.height and similar modifiers set the total host height, within which the chart and its components are fitted.

Animation

For model producers, animationSpec defines how differences between models are animated. initialAnimationSpec separately defines the initial animation and defaults to animationSpec. Set initialAnimationSpec to null to skip the initial animation.

Scroll

CartesianChartHost accepts VicoScrollState instances, enabling scroll customization and programmatic scrolling. Use rememberVicoScrollState to instantiate VicoScrollState:

val scrollState = rememberVicoScrollState(/* ... */)
CartesianChartHost(scrollState = scrollState, /* ... */)

From a coroutine, call VicoScrollState.scroll to scroll immediately or VicoScrollState.animateScroll to animate the change.

To snap the scroll position to multiples of an x-step after a fling, set xSnapStep. Use snapAnimationSpec to customize the animation.

When the data’s minimum x-value or x-step changes, the scroll state preserves the visible x-range. For example, prepending historical data doesn’t move the viewport to the new start edge.

Scroll represents scroll values—either absolute (from zero) or relative (from the current value). Scroll.Absolute and Scroll.Relative cover the two cases. The following factory functions are available:

• Absolute.pixels
• Absolute.x
• Relative.pixels
• Relative.x

AutoScrollCondition defines when to scroll automatically. There are two singletons:

• Never (default)
• OnModelGrowth

You can create custom implementations of Scroll and AutoScrollCondition for more specific behavior.

Zoom

CartesianChartHost accepts VicoZoomState instances, enabling zoom customization. Use rememberVicoZoomState to instantiate VicoZoomState:

val zoomState = rememberVicoZoomState(/* ... */)
CartesianChartHost(zoomState = zoomState, /* ... */)

From a coroutine, call VicoZoomState.zoom to zoom immediately or VicoZoomState.animateZoom to animate the change.

Zoom defines zoom factors. The following singletons and factory functions are available:

• Content
• max
• min
• fixed
• x

You can create custom implementations of Zoom for more specific behavior.