Koala Plot draws Compose charts that run on four platforms

One chart API for four platforms

Koala Plot is a Compose Multiplatform based charting and plotting library, allowing you to build interactive charts for Android, desktop, iOS and the web using a single API and code base.

The Compose Multiplatform base is the whole design decision, and it has consequences in both directions. A team that has already committed to Compose Multiplatform gets a charting library that looks and behaves like the rest of their UI code, on every target. A team that has not gets a library that requires them to adopt Compose Multiplatform for the chart, which is a larger decision than picking a chart library.

The library is written in Kotlin, published to Maven Central as io.github.koalaplot:koalaplot-core, and the badge shows Kotlin 2.1.0. The licence is MIT, and the documentation is generated with Dokka.

The project also publishes a web version of the samples, which is the fastest way to judge the visual quality before writing any code, and a separate samples repository with complete build files and code examples.

The status is described honestly in the README. The project is in a developmental state, several plot types are available and stable, and it is expected that the API surface and functionality will change as the maintainers gain experience using the library in applications. API and binary compatibility might not be maintained between 0.x releases, but the project strives to maintain API compatibility between minor versions. That sentence is the single most important fact for an adopter, and it is why the 0.x line should be pinned.

The elements of a plot are Composables

Most elements of a plot are Composables and can therefore be easily customized, including colors, fonts, borders, shapes and user interaction.

That single sentence explains the API. There is no separate style object, no theme file for the chart and no configuration DSL for colours. A slice of a pie chart is a Composable, so it is a function you write. An axis label is a Composable, so it can be any layout you like, including a column with two lines of differently styled text. A connector between a slice and its label is a Composable, and the library ships linear and Bezier implementations you can replace.

The pie and donut chart entry is the clearest illustration. It has Composable slices with a default implementation that can react to hovering, optional Composable labels and Composable connectors with provided linear and Bezier implementations, Composable content for the centre of a donut chart, and a customizable first-draw animation.

The same pattern appears in the line graph, where the axis titles and value labels are Composable, the symbols at data points are optional Composables, and the curves can be linear, stairstep or Bezier smoothed. In the vertical bar graph the bars themselves are Composable with a provided default implementation.

The practical consequence is that a chart is assembled in Kotlin, and the library's role is to supply the geometry, the scales and the interaction while leaving the appearance to you. If your team is comfortable in Compose, that is a good fit. If you expected a drop-in widget with a handful of styling options, it is not.

Which plot types are there, and which are stable

The feature list in the README is a catalogue of what a charting library needs to cover, and it is worth reading as a checklist of what you can build today.

There is a pie and donut chart, a line graph, stacked area graphs, a vertical bar graph, a bullet graph, radar, polar and spider plots, heatmaps, a chart layout component and legends.

Each has its own detail. Line graphs support linear or log axes, numeric or category axes, optional shaded areas for an area chart, zoom and pan on one or both axes, mouse tracking and annotations. The vertical bar graph handles clustered and stacked bars, supports negative values and bars that do not start at zero, and has a customizable first-draw animation. Stacked area graphs plot multiple lines with shaded areas between them and accumulated values, with a similar feature set to the line chart. The bullet graph supports individual or multiple vertically aligned bullet graphs. Radar, polar and spider plots draw lines, areas, symbols or a combination with a configurable origin position and clockwise or counter-clockwise angle orientation. The chart layout combines an optional Composable title, plot and legend in any of four positions, and legends come in a single column and a flow layout.

Two limits are stated rather than implied. Zoom and pan on the vertical bar graph are not available for mobile platforms within js and wasmJs, which is a real constraint for a chart library whose whole point is running everywhere. And the project is careful to say that several plot types are available and stable while the project as a whole is in a developmental state, so the honest reading is that the plot types listed are usable and the API around them will still move.

Adding the dependency and writing a first chart

Getting started is three steps, and the first two are build file changes.

The mavenCentral repository goes into the project's build.gradle.kts:

repositories {
  mavenCentral()
}

and the core module comes in as a dependency:

dependencies {
  implementation("io.github.koalaplot:koalaplot-core:0.12.1")
}

The README also points at the samples repository for a complete build.gradle.kts rather than a fragment, which is the sensible thing to copy when you are setting the module up for the first time.

The third step is writing the chart, and the bullet graph example shows what the API feels like:

BulletGraphs {
  bullet(FloatLinearAxisModel(0f..300f)) {
    label {
      Column(
        horizontalAlignment = Alignment.End,
        modifier = Modifier.padding(end = KoalaPlotTheme.sizes.gap)
      ) {
        Text("Revenue 2005 YTD", textAlign = TextAlign.End)
        Text(
          "(US $ in thousands)",
          textAlign = TextAlign.End,
          style = MaterialTheme.typography.labelSmall
        )
      }
    }
    axis { labels { Text("${it.toInt()}") } }
    comparativeMeasure(260f)
    featuredMeasureBar(275f)
    ranges(0f, 200f, 250f, 300f)
  }
}

Read it as a description of the chart. The axis model is a FloatLinearAxisModel over a range, the label block is a plain Compose Column with two Texts styled from MaterialTheme, the axis labels are a Composable that formats the value, and the measures and ranges are named numbers. The chart is a function call, and the parts you want to change are slots you fill in.

There is also a KoalaPlotTheme with sizes that the example uses for spacing, which is the one place the library does supply a theme, for spacing rather than for appearance.

Interaction is part of the API, not an afterthought

Several of the plot types carry real interaction, and the way it is described tells you what to expect.

The pie chart has composable slices with a default implementation that can react to hovering, and optional composable labels and connectors, which means a hover state can drive a label that moves with the pointer. The line graph supports zoom and pan on one or both axes, mouse tracking and annotations. The vertical bar graph has the same zoom and pan, with the stated exception of mobile platforms within js and wasmJs, plus a customizable first-draw animation, as does the pie and donut chart.

That combination is what separates a plotting library from a picture of a chart. A chart that supports pan and zoom and mouse tracking can be used to explore a dataset; a chart that renders a static image of the same data cannot.

The cost of the composable approach shows up in those same features. A hover response has to be written as a Composable that reacts to pointer state, and the default implementations are starting points rather than finished behaviour. A chart that has to look and behave a certain way will take more Kotlin than one where a style object sets the options.

The documentation is Dokka-generated API documentation for the current build, with a second link pinned to the 0.12.1 release, and the sample repository carries the runnable code.

Where Koala Plot is the wrong tool

The boundaries are clear and they are mostly consequences of the Compose Multiplatform base.

First, it needs Compose Multiplatform. There is no path for a team that renders its UI in SwiftUI, in UIKit, in React, or in a server side stack. Adding a Compose Multiplatform module to a project that does not have it is a significant decision, and the chart is the smaller half of that cost.

Second, the version line is 0.x and the project says so. API and binary compatibility might not be maintained between 0.x releases, and the API surface and functionality are expected to change as the maintainers learn from using it in applications. A 0.12.0 to 0.13.0 upgrade is a migration project, and the mitigation is to pin the version and read the changelog before moving.

Third, the composition is the price of the flexibility. Every element is a Composable, so a chart that has to look a specific way takes a lot of Kotlin. Teams that want a chart configured with a handful of properties will find the API verbose, and teams that want a fully bespoke chart will find it the right shape.

Fourth, the coverage is uneven in the ways charts usually are. Heatmaps and bullet graphs are listed, and there is no mention of scatter plots beyond an example image, no financial chart types such as candlesticks, and no map or network layouts. A requirement in those directions means looking elsewhere.

And fifth, for a static report, none of this is needed. If the output is a PNG in a build, an offline chart generator that writes an image is simpler and cheaper than a Compose UI you then have to render and capture.

Editorial conclusion

Kotlin teams that already build with Compose Multiplatform and want charts that run on Android, desktop, iOS and the web from one code base should try Koala Plot, because the composable-per-element design means a chart can be restyled in Kotlin rather than through a theming layer, and several plot types are already stable. It is the wrong choice for a team that is not on Compose Multiplatform, and it is the wrong choice if you need a stable API, since the project states that API and binary compatibility might not be maintained between 0.x releases. Before adopting, check that the plot types you need are in the list rather than on the roadmap, and pin the exact version you test against, because the current release line is 0.12.x.

Frequently asked questions

Official sources

1. KoalaPlot/koalaplot-core on GitHub
2. License: MIT
3. Project website
4. README
5. Releases