Support positioning axis title above the vertical axis

[dmitry-stakhov]

Problem

When building financial charts with a Y-axis unit label (e.g. "USD", "%"), it's common to place that label above the vertical axis, directly on top of the first tick label.

Currently, VerticalAxis supports a title / titleComponent parameter, but the title is always drawn rotated 90 degrees and vertically centered alongside the axis. There is no option to place it horizontally at the top.

Current workaround

Overlay a separate Text composable on top of CartesianChartHost with a manually calculated negative Y offset:

Box {
    CartesianChartHost(
        chart = rememberCartesianChart(
            startAxis = VerticalAxis.rememberStart(
                label = axisLabelComponent,
                // no built-in way to add a top-positioned title
            ),
            // ...
        ),
        // ...
    )
    // Manual overlay with offset calculated from axis label height
    val labelHeight = with(density) {
        textMeasurer.measure("0", axisLabelStyle).size.height.toDp()
    }
    Text(
        text = "USD",
        modifier = Modifier.offset(x = 2.dp, y = -(labelHeight * 3 / 2)),
        style = axisLabelStyle,
    )
}

This is fragile because:

• It relies on knowing Vico's internal top inset (half the tick label height)
• It breaks if the axis layout or padding logic changes between versions
• The offset must be recalculated when font size or axis configuration changes

Proposal

Add a titlePosition parameter to VerticalAxis that controls where the title is placed:

enum class TitlePosition {
    Center,  // current behavior: rotated 90°, vertically centered
    Top,     // horizontal text, placed above the topmost tick label
}

VerticalAxis.rememberStart(
    titleComponent = rememberTextComponent(...),
    title = { "USD" },
    titlePosition = TitlePosition.Top,
)

When TitlePosition.Top is used, the title would be drawn horizontally (no rotation) and positioned directly above the first tick label, with the axis accounting for the title height in its top inset.

Environment

• Vico version: 3.1.0
• Compose Multiplatform project (Android + iOS)

[github-actions[bot]]

Thanks for the detailed write-up — we’ll look into adding first-class support for this.

In the meantime, a more robust workaround than overlaying a Text composable is to subclass VerticalAxis and override drawOverLayers to draw the title horizontally above bounds.top (and updateLayerMargins / getWidth to reserve the necessary space). That keeps the title inside Vico’s layout pipeline, so it stays correctly positioned across font-size, axis-config, and version changes without depending on internal inset math.