Skip to main content
Version: 2.0.0-beta.2

Hosts

To display a CartesianChart, use a host. The hosts act as entry points. Either one accepts a CartesianChart, a CartesianChartModelProducer, and extra elements and configuration options not handled directly by CartesianCharts. The hosts are responsible for showing placeholders when no data is available.

The host for Jetpack Compose is the CartesianChartHost composable function. It’s interacted with via its parameters. A CartesianChart is created via rememberCartesianChart and passed in via the chart parameter:

CartesianChartHost(chart = rememberCartesianChart(...), ...)

Scroll and zoom​

One of the key responsibilities of the hosts is handling scroll and zoom, which you can customize.

CartesianChartHost accepts instances of VicoScrollState and VicoZoomState. Use rememberVicoScrollState and rememberVicoZoomState to instantiate these classes:

val scrollState = rememberVicoScrollState(...)
val zoomState = rememberVicoZoomState(...)
CartesianChartHost(scrollState = scrollState, zoomState = zoomState, ...)

You can toggle user scroll, set the initial scroll, add and customize automatic scrolling (which occurs on data updates), read the scroll position, and scroll programmatically (with or without an animation). Scroll values and deltas are represented by Scroll, which is split into Scroll.Absolute and Scroll.Relative. Scroll.Absolute.Companion and Scroll.Relative.Companion house singletons and factory functions, which let you perform the following scrolls:

  • to the start
  • to the end
  • to a specific position in pixels
  • to a specific x value (for which you can specify an alignment)
  • by a specific number of pixels
  • by a specific number of x units

You can toggle user zoom, read the zoom factor, and set the initial, minimum, and maximum zooms. Zoom factors are represented by Zoom. Zoom.Companion houses singletons and factory functions, which let you do the following:

  • Make the content fill the viewport.
  • Use a static zoom factor.
  • Ensure that a specific number of x units is visible.
  • Use the minimum of two Zooms.
  • Use the maximum of two Zooms.

XML attributes​

tip

If you’re using Jetpack Compose, skip this section.

CartesianChartView has the following XML attributes:

  • *AxisStyle (AxisStyle): the style of a specific chart axis
  • *fadingEdgeWidth (dimension): the width of a specific fading edge
  • axisStyle (AxisStyle): the style of all chart axes
  • candlestickLayerStyle (CandlestickCartesianLayerStyle): the CandlestickCartesianLayer style
  • columnLayerStyle (ColumnCartesianLayerStyle): the style of column charts
  • fadingEdgeVisibilityInteropolator (path to TimeInterpolator implementation): the visibility interpolator for fading edges
  • fadingEdgeVisibilityThreshold (dimension): the visibility threshold for the fading edges
  • fadingEdgeWidth (dimension): the width of both fading edges
  • layers (|-separated list of candlestick, column, and line): the CartesianLayers
  • lineLayerStyle (LineCartesianLayerStyle): the style of line charts
  • scalableEndLayerPadding (dimension): equivalent to the scalableEndPaddingDp parameter of the CartesianLayerPadding constructor
  • scalableStartLayerPadding (dimension): equivalent to the scalableStartPaddingDp parameter of the CartesianLayerPadding constructor
  • scrollEnabled (boolean): whether to enable horizontal scrolling
  • show*Axis (boolean): whether to show a specific axis
  • unscalableEndLayerPadding (dimension): equivalent to the unscalableEndPaddingDp parameter of the CartesianLayerPadding constructor
  • unscalableStartLayerPadding (dimension): equivalent to the unscalableStartPaddingDp parameter of the CartesianLayerPadding constructor
  • zoomEnabled (boolean): whether to enable zooming

Attribute sets​

AxisStyle​

  • addExtremeHorizontalAxisLabelPadding (boolean): equivalent to the addExtremeLabel parameter of AxisItemPlacer.Horizontal.default
  • guidelineStyle (LineComponentStyle): the style of axis guidelines
  • horizontalAxisItemPlacer (aligned or segmented): the HorizontalAxis.ItemPlacer—see AxisItemPlacer.Horizontal.aligned and AxisItemPlacer.Horizontal.segmented
  • horizontalAxisLabelOffset (integer): the label offset for this axis if it is horizontal
  • horizontalAxisLabelSpacing (integer): the label spacing for this axis if it is horizontal
  • labelBackground (color or ShapeStyle): the background for axis labels
  • labelRotationDegrees (floating-point number): the rotation of axis labels in degrees
  • labelStyle (TextComponentStyle): the style of axis labels
  • lineStyle (LineComponentStyle): the style of the axis line
  • shiftExtremeHorizontalAxisLines (boolean): equivalent to the shiftExtremeLines parameters of AxisItemPlacer.Horizontal.aligned and AxisItemPlacer.Horizontal.segmented
  • shiftTopVerticalAxisLines (boolean): equivalent to the shiftTopLines parameter of AxisItemPlacer.Vertical.count
  • showGuidelines (boolean): whether to display guidelines
  • showLine (boolean): whether to display the axis line
  • showTick (boolean): whether to display ticks
  • showTitle (boolean or reference): whether to display the axis title
  • tickLength (dimension): the length of axis ticks
  • tickStyle (LineComponentStyle): the style of axis ticks
  • titleStyle (TextComponentStyle): the style of the axis title
  • title (string or reference): the axis title
  • verticalAxisHorizontalLabelPosition (outside or inside): the horizontal position of the labels on this axis if it is vertical
  • verticalAxisItemCount (integer): equivalent to the itemCount parameter of AxisItemPlacer.Vertical.count
  • verticalAxisVerticalLabelPosition (top, center, or bottom): the vertical position of the labels on this axis is if it vertical

CandlestickCartesianLayerStyle​

CandleStyle​

ColumnCartesianLayerStyle​

  • column1Style (ComponentStyle): the style for columns whose index in a column collection is 3k (k ∈ N)
  • column2Style (ComponentStyle): the style for columns whose index in a column collection is 1 + 3k (k ∈ N)
  • column3Style (ComponentStyle): the style for columns whose index in a column collection is 2 + 3k (k ∈ N)
  • columnCollectionSpacing (dimension): the distance between neighboring column collections
  • dataLabelRotationDegrees (floating-point number): the rotation of data labels in degrees
  • dataLabelStyle (TextComponentStyle): the style of data labels
  • dataLabelVerticalPosition (top, center, or bottom): the vertical position of each data label relative to the top edge of its respective column
  • groupedColumnSpacing (dimension): the distance between neighboring grouped columns
  • showDataLabels (boolean): whether to show data labels

ComponentStyle​

  • color (color): the background color
  • overlayingComponentPadding (dimension): the padding between this component and the component with which it is overlaid
  • overlayingComponentStyle (ComponentStyle): a component with which to overlay this component
  • shapeStyle (ShapeStyle): the shape style
  • strokeColor (color): the stroke color
  • strokeThickness (dimension): the stroke thickness

TextComponentStyle​

  • android:color (color): the text color
  • android:ellipsize (start, end, middle, none, or marquee): the text truncation behavior
  • android:fontFamily (sans-serif, sans-serif-*, or @font reference): the font family
  • android:fontStyle (normal or italic): the font style
  • android:padding* (dimension): the padding for a specific edge or edge pair of the label
  • android:padding (dimension): the padding for each edge of the label
  • android:textFontWeight (integer between 100 and 900): the font weight
  • android:textSize (dimension): the text size
  • backgroundStyle (ComponentStyle): the background for the label
  • margin* (dimension): the size of a specific margin or margin pair
  • margin (dimension): the size of all four margins
  • textAlignment (normal, center, or opposite): the text alignment
  • typeface (normal, sans, serif, or monospace): the typeface

LineCartesianLayerStyle​

  • line1Style (LineStyle): the style for lines whose index in the list of lines in a line chart is 3k (k ∈ N)
  • line2Style (LineStyle): the style for lines whose index in the list of lines in a line chart is 1 + 3k (k ∈ N)
  • line3Style (LineStyle): the style for lines whose index in the list of lines in a line chart is 2 + 3k (k ∈ N)
  • pointSpacing (dimension): the point spacing

LineComponentStyle​

  • color (color): the background color
  • shapeStyle (ShapeStyle): the shape of the line
  • strokeColor (color): the stroke color
  • strokeThickness (dimension): the stroke thickness
  • thickness (dimension): the line thickness

LineStyle​

  • color (color): the line color
  • curvature (fraction): the strength of the cubic Bézier curve between each key point on the line
  • dataLabelRotationDegrees (floating-point number): the rotation of data labels in degrees
  • dataLabelStyle (TextComponentStyle): the style of data labels
  • dataLabelVerticalPosition (top, center, or bottom): the vertical position of each data label relative to its respective point on the line
  • gradientBottomColor (color): the bottom color of the vertical background gradient
  • gradientTopColor (color): the top color of the vertical background gradient
  • pointSize (dimension): the point size
  • pointStyle (ComponentStyle): the style of points
  • showDataLabels (boolean): whether to show data labels
  • thickness (dimension): the thickness of the line

ShapeStyle​

  • bottomEndCornerSize (dimension or faction): the size of the bottom-end corner
  • bottomStartCornerSize (dimension or fraction): the size of the bottom-start corner
  • cornerSize (dimension or fraction): the corner size
  • cornerTreatment (rounded or cut): the corner style
  • dashLength (dimension): the dash length (0 means no dashes)
  • gapLength (dimension): the dash gap length (0 means no dashes)
  • topEndCornerSize (dimension or fraction): the size of the top-end corner
  • topStartCornerSize (dimension or fraction): the size of the top-start corner