Skip to main content
Version: 2.0.0-alpha.19

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 (Axis): the style of all chart axes
  • *AxisStyle (Axis): the style of a specific chart axis
  • candlestickLayerStyle (CandlestickLayerStyle): the CandlestickCartesianLayer style
  • columnLayerStyle (ColumnLayerStyle): the style of column charts
  • lineLayerStyle (LineLayerStyle): the style of line charts
  • show*Axis (boolean): whether to show a specific axis
  • chartHorizontalScrollingEnabled (boolean): whether to enable horizontal scrolling
  • chartZoomEnabled (boolean): whether to enable zooming
  • fadingEdgeWidth (dimension): the width of both fading edges
  • *fadingEdgeWidth (dimension): the width of a specific fading edge
  • fadingEdgeVisibilityThreshold (dimension): the visibility threshold for the fading edges
  • fadingEdgeVisibilityInteropolator (path to TimeInterpolator implementation): the visibility interpolator for fading edges
  • horizontalLayout (segmented or fullWidth): the chart’s HorizontalLayout
  • layers (|-separated list of candlestick, column, and line): the CartesianLayers
  • scalableStartContentPadding (dimension): equivalent to HorizontalLayout.FullWidth#scalableStartPaddingDp
  • scalableEndContentPadding (dimension): equivalent to HorizontalLayout.FullWidth#scalableEndPaddingDp
  • unscalableStartContentPadding (dimension): equivalent to HorizontalLayout.FullWidth#unscalableStartPaddingDp
  • unscalableEndContentPadding (dimension): equivalent to HorizontalLayout.FullWidth#unscalableEndPaddingDp

Attribute sets​

Axis​

  • axisLineStyle (LineComponentStyle): the style of the axis line
  • axisGuidelineStyle (LineComponentStyle): the style of axis guidelines
  • axisTickStyle (LineComponentStyle): the style of axis ticks
  • axisLabelStyle (TextComponentStyle): the style of axis labels
  • axisTickLength (dimension): the length of axis ticks
  • axisLabelBackground (color or Shape): the background for axis labels
  • verticalAxisHorizontalLabelPosition (outside or inside): the horizontal position of the labels on this axis if it is vertical
  • verticalAxisVerticalLabelPosition (top, center, or bottom): the vertical position of the labels on this axis is if it vertical
  • labelRotationDegrees (floating-point number): the rotation of axis labels in degrees
  • title (string or reference): the axis title
  • showTitle (boolean or reference): whether to display the axis title
  • titleStyle (TextComponentStyle): the style of the axis title
  • horizontalAxisLabelSpacing (integer): the label spacing for this axis if it is horizontal
  • horizontalAxisLabelOffset (integer): the label offset for this axis if it is horizontal
  • showAxisLine (boolean): whether to display the axis line
  • showGuideline (boolean): whether to display guidelines
  • showTick (boolean): whether to display ticks
  • shiftExtremeHorizontalAxisTicks (boolean): equivalent to the shiftExtremeTicks parameter of AxisItemPlacer.Horizontal.default
  • addExtremeHorizontalAxisLabelPadding (boolean): equivalent to the addExtremeLabel parameter of AxisItemPlacer.Horizontal.default
  • shiftTopVerticalAxisLines (boolean): equivalent to the shiftTopLines parameter of AxisItemPlacer.Vertical.count
  • maxVerticalAxisItemCount (integer): equivalent to the maxItemCount parameter of AxisItemPlacer.Vertical.count

CandleStyle​

ComponentStyle​

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

CandlestickLayerStyle​

ColumnLayerStyle​

  • 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)
  • columnOuterSpacing (dimension): the distance between neighboring column collections
  • columnInnerSpacing (dimension): the distance between neighboring grouped columns
  • showDataLabels (boolean): whether to show data labels
  • 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
  • dataLabelRotationDegrees (floating-point number): the rotation of data labels in degrees

TextComponentStyle​

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

LineComponentStyle​

  • color (color): the background color
  • thickness (dimension): the line thickness
  • shapeStyle (Shape): the shape of the line
  • strokeColor (color): the stroke color
  • strokeWidth (dimension): the stroke width

LineLayerStyle​

  • line1Spec (LineSpec): the style for lines whose index in the list of lines in a line chart is 3k (k ∈ N)
  • line2Spec (LineSpec): the style for lines whose index in the list of lines in a line chart is 1 + 3k (k ∈ N)
  • line3Spec (LineSpec): the style for lines whose index in the list of lines in a line chart is 2 + 3k (k ∈ N)
  • spacing (dimension): the point spacing

LineSpec​

  • color (color): the line color
  • gradientTopColor (color): the top color of the vertical background gradient
  • gradientBottomColor (color): the bottom color of the vertical background gradient
  • pointSize (dimension): the point size
  • lineThickness (dimension): the thickness of the line
  • pointStyle (ComponentStyle): the style of points
  • cubicStrength (fraction): the strength of the cubic bezier curve between each key point on the line
  • showDataLabels (boolean): whether to show data labels
  • 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
  • dataLabelRotationDegrees (floating-point number): the rotation of data labels in degrees

Shape​

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