Histogram Chart

Overview

HistogramChart displays a distribution from precomputed bin heights. Each input value is one bin's height and each category labels that bin; the chart does not group raw observations or calculate statistical bin boundaries. Use it when your application has already grouped a numeric distribution, such as request counts by duration interval.

implementation("io.github.hdcharts:histogram:3.1.0")

Histogram Demo

Recording source: HistogramExample.kt.

Basic Usage

Each RequestDurationBin already contains an interval and its counted requests. The chart renders these equal-width bins as adjacent bars; it does not derive them from individual request durations.

import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import io.github.hdcharts.core.model.toChartData
import io.github.hdcharts.histogram.HistogramChart

private data class RequestDurationBin(
    val interval: String,
    val requestCount: Double,
)

@Composable
fun ShowRequestDurationDistribution(modifier: Modifier = Modifier) {
    // Counts have already been grouped into these equal-width intervals.
    val bins =
        listOf(
            RequestDurationBin("0–25 ms", 4.0),
            RequestDurationBin("25–50 ms", 18.0),
            RequestDurationBin("50–75 ms", 47.0),
            RequestDurationBin("75–100 ms", 72.0),
            RequestDurationBin("100–125 ms", 58.0),
            RequestDurationBin("125–150 ms", 31.0),
        )
    val data =
        bins.toChartData(
            value = { it.requestCount },
            category = { it.interval },
            seriesName = "Requests",
        )

    HistogramChart(
        data = data,
        modifier = modifier,
        title = "Request Duration",
    )
}

Histogram showing request duration distribution

Capabilities

Bin Width and Compact Mode

Histogram bins have zero spacing and a default minimum width of 10.dp. When the bins no longer fit at that width, compact mode combines neighboring bins for display. A compact bar shows the average height of its source bins, while selection still identifies the middle source bin. Expanding the chart reveals every bin. Increasing the minimum width makes the chart enter compact mode with fewer visible bins. This excerpt reuses data from Basic Usage.

@Composable
fun ShowWiderRequestBins(data: ChartData) {
    HistogramChart(
        data = data,
        style =
            HistogramChartDefaults.style(
                bars = HistogramChartDefaults.bars(minBarWidth = 16.dp),
            ),
    )
}

Gradients

One horizontal teal-to-lime-to-amber gradient spans the plot, so colors transition across the duration bins instead of repeating in every bin. The excerpt reuses data from Basic Usage.

@Composable
fun RequestDurationGradient(data: ChartData) {
    val colors =
        listOf(
            Color(0xFF0F766E),
            Color(0xFF84CC16),
            Color(0xFFF59E0B),
        )
    val gradient = ChartGradients.horizontal(colors = colors, span = GradientSpan.Plot)

    HistogramChart(
        data = data,
        style =
            HistogramChartDefaults.style(
                bars = HistogramChartDefaults.bars(gradient = gradient),
            ),
    )
}