Axes

You can display an axis along each of the four edges of a CartesianChart. There are two axes: HorizontalAxis and VerticalAxis. Numerous customization options are available—you can change the appearance of the labels, modify the axis lines, add titles, and more. The itemPlacer parameters and properties let you apply AxisItemPlacer.Horizontal and AxisItemPlacer.Vertical instances, enabling you to customize for what x and y values labels and lines are displayed. Three factory functions are available: AxisItemPlacer.Horizontal.default, AxisItemPlacer.Vertical.step, and AxisItemPlacer.Vertical.count.

tip

For information on x and y range customization, see the “AxisValueOverrider” section of the CartesianLayer introduction page.

Compose

Use the rememberStartAxis, rememberTopAxis, rememberEndAxis, and rememberBottomAxis functions to create axes:

CartesianChartHost(
    chart = rememberCartesianChart(
        startAxis = rememberStartAxis(...),
        topAxis = rememberTopAxis(...),
        endAxis = rememberEndAxis(...),
        bottomAxis = rememberBottomAxis(...),
        ...
    ),
    ...
)

For the label, axis, tick, and guideline parameters of these functions, you can use rememberAxisLabelComponent, rememberAxisLineComponent, rememberAxisTickComponent, and rememberAxisGuidelineComponent, which have more suitable defaults than rememberTextComponent and rememberLineComponent.

Views

Use the XML attributes to create axes:

<com.patrykandpatrick.vico.views.cartesian.CartesianChartView
    android:id="@+id/chart_view"
    app:showStartAxis="true"
    app:showTopAxis="true"
    app:showEndAxis="true"
    app:showBottomAxis="true"
    ... />

Alternatively, use HorizontalAxis.build and VerticalAxis.build:

cartesianChartView.chart.startAxis = VerticalAxis.build { ... }
cartesianChartView.chart.topAxis = HorizontalAxis.build { ... }
cartesianChartView.chart.endAxis = VerticalAxis.build { ... }
cartesianChartView.chart.bottomAxis = HorizontalAxis.build { ... }

Value formatting

You can use CartesianValueFormatter to format the values displayed along axes. There are two factory functions: CartesianValueFormatter.decimal and CartesianValueFormatter.yPercent. For more complex use cases (dates, temperatures, category axes, etc.), you can create custom implementations.

Category axes

Let’s say we’re looking to create a column chart for the following data:

val data = mapOf("A" to 8f, "B" to 4f, "C" to 6f)

We’ll be using an extra for the labels, so we create a key for it:

val labelListKey = ExtraStore.Key<List<String>>()

We add the data to the chart like so:

cartesianChartModelProducer.tryRunTransaction {
    columnSeries { series(data.values) }
    updateExtras { it[labelListKey] = data.keys.toList() }
}

And here’s the CartesianValueFormatter for the bottom axis:

CartesianValueFormatter { x, chartValues, _ -> chartValues.model.extraStore[labelListKey][x.toInt()] }

Dates

In the following example, we demonstrate how to create a line chart for a mapping of dates to y values, with the dates spaced out proportionally. (For non-proportional spacing, use the approach described under “Category axes.”) This is the data:

val data =
    mapOf(
        LocalDate.parse("2022-07-01") to 2f,
        LocalDate.parse("2022-07-02") to 6f,
        LocalDate.parse("2022-07-04") to 4f,
    )

Once again, an extra will be needed. We create a key for it:

val xToDateMapKey = ExtraStore.Key<Map<Float, LocalDate>>()

We transform the data and add it to the chart like so:

val xToDates = data.keys.associateBy { it.toEpochDay().toFloat() }
cartesianChartModelProducer.tryRunTransaction {
    lineSeries { series(xToDates.keys, data.values) }
    updateExtras { it[xToDateMapKey] = xToDates }
}

We create a custom CartesianValueFormatter for the bottom axis:

val dateTimeFormatter = DateTimeFormatter.ofPattern("d MMM")

CartesianValueFormatter { x, chartValues, _ ->
    (chartValues.model.extraStore[xToDateMapKey][x] ?: LocalDate.ofEpochDay(x.toLong()))
        .format(dateTimeFormatter)
}