Funnel Chart

A funnel: the stages of something that fewer and fewer get through, one under another, each as wide as the number that reached it. It shows where the others were lost: the visitors who signed up, the sign-ups who tried, the trials who paid.

import com.pantrixui.components.chart.funnel.PantrixFunnelChart

• Shape. The largest stage is as wide as the chart; each stage narrows to the width of the one after it, and the stages make one funnel. The last keeps its width. A stage larger than the one before it does not narrow but widens: the chart draws what it is given. shape = FunnelShape.Bars draws each stage as a bar as wide as its value; horizontal lays the stages side by side from where lines start, each as tall as its value.
• Words. A stage's name and value are written in it; beside the value stands its share: of the first stage, of the one before, or both (rate). A stage too narrow for its words has its name and value beside it, under it in a horizontal funnel; where there is room for neither, only the name is left. labels = null writes nothing.
• The stage pointed at. The stage whose row the pointer or a finger is on is ringed, and the tooltip writes its name, its value and its share. On the keyboard the arrows go from stage to stage: up and down, right and left in a horizontal funnel.
• Colours. Each stage takes one of the theme's chart colours, by its place; the color field of FunnelStage gives a stage its own.
• Export. export puts a button over the chart: the chart is made, as it is on the screen and without the part that is pointed at or its tooltip, into a PNG, an SVG or a PDF file and handed to the app.
• Automation. The chart is tagged Funnel_<tagKey>, and a stage Funnel_<tagKey>.Stage_<number>. A press on a stage is reported as a select event with the stage's key.

Examples

From a visit to a payment

At its plainest: the stages, given in their order. Each stage has a key, a name and a value.

Move the pointer over a stage's row, or touch the stage: the stage is ringed and the tooltip writes its value, with its share of the first stage.

PantrixFunnelChart(
    stages = FUNNEL_STEPS,
    description = "The stages a visit goes through until it comes to a payment",
    tagKey = "plain"
)

private val FUNNEL_STEPS = listOf(
    FunnelStage("visits", "Visits", 3000),
    FunnelStage("signups", "Sign-ups", 1240),
    FunnelStage("trials", "Trials", 520),
    FunnelStage("paid", "Paid", 310)
)

Shape and direction

The stages' shape and direction. "Bars" draws each stage as a bar as wide as its value (shape = FunnelShape.Bars); turn the switch: the stages stand side by side (horizontal = true), each as tall as its value. The arrows on the keyboard then go right and left.

var shape by remember { mutableStateOf(FunnelShape.Funnel) }
var horizontal by remember { mutableStateOf(false) }
PantrixSegmentButton(
    options = FUNNEL_SHAPES,
    selected = shape,
    onSelect = { shape = it },
    fullWidth = false,
    tagKey = "funnel_shape"
)
PantrixSwitchButton(
    checked = horizontal,
    onCheckedChange = { horizontal = it },
    label = "Horizontal",
    tagKey = "funnel_horizontal"
)
PantrixFunnelChart(
    stages = FUNNEL_STEPS,
    shape = shape,
    horizontal = horizontal,
    description = "The stages a visit goes through until it comes to a payment",
    tagKey = "shape"
)

private val FUNNEL_STEPS = listOf(
    FunnelStage("visits", "Visits", 3000),
    FunnelStage("signups", "Sign-ups", 1240),
    FunnelStage("trials", "Trials", 520),
    FunnelStage("paid", "Paid", 310)
)

private val FUNNEL_SHAPES = listOf(
    SegmentOption(value = FunnelShape.Funnel, label = "Funnel", tagKey = "funnel"),
    SegmentOption(value = FunnelShape.Bars, label = "Bars", tagKey = "bars")
)

Conversion rates

Conversion rates (rate). "Of the first" writes each stage's share of the first stage, "Of the previous" how many of those who reached the stage before went on to this one, "Both" the two together. On the stage the shares stand bare, two of them apart by a dot; the tooltip and a screen reader say what each share is of.

var rate by remember { mutableStateOf(FunnelRate.Previous) }
PantrixSegmentButton(
    options = FUNNEL_RATES,
    selected = rate,
    onSelect = { rate = it },
    fullWidth = false,
    tagKey = "funnel_rate"
)
PantrixFunnelChart(
    stages = FUNNEL_STEPS,
    rate = rate,
    description = "The stages of a visit up to a payment, with conversion rates",
    tagKey = "rates"
)

private val FUNNEL_STEPS = listOf(
    FunnelStage("visits", "Visits", 3000),
    FunnelStage("signups", "Sign-ups", 1240),
    FunnelStage("trials", "Trials", 520),
    FunnelStage("paid", "Paid", 310)
)

private val FUNNEL_RATES = listOf(
    SegmentOption(value = FunnelRate.First, label = "Of the first", tagKey = "first"),
    SegmentOption(value = FunnelRate.Previous, label = "Of the previous", tagKey = "previous"),
    SegmentOption(value = FunnelRate.Both, label = "Both", tagKey = "both")
)

Values written short

Large numbers are written short (the format of ChartDataLabels): they leave room in the stages. Turn the switch: the words go away (labels = null) and the values stay in the tooltip and for the screen reader alone.

var written by remember { mutableStateOf(true) }
val strings = PantrixTheme.strings
PantrixSwitchButton(
    checked = written,
    onCheckedChange = { written = it },
    label = "Words",
    tagKey = "funnel_labels"
)
PantrixFunnelChart(
    stages = CAMPAIGN_STEPS,
    labels = if (written) ChartDataLabels(format = { strings.compact(it) }) else null,
    description = "The stages of a campaign, from being shown to a sale",
    tagKey = "labels"
)

private val CAMPAIGN_STEPS = listOf(
    FunnelStage("shown", "Shown", 1_250_000),
    FunnelStage("clicks", "Clicks", 410_000),
    FunnelStage("carts", "Carts", 96_000),
    FunnelStage("orders", "Orders", 38_500),
    FunnelStage("repeat", "Bought again", 9_200)
)

Pressing a stage

A press is handed the stage: its key is in its series, its name in its name, its value in its value, and what the chart writes in its text. Press a stage: the line below writes what was pressed.

var pressed by remember { mutableStateOf<String?>(null) }
PantrixFunnelChart(
    stages = FUNNEL_STEPS,
    onSelect = { pressed = "${it.name}: ${it.text}" },
    description = "The stages a visit goes through until it comes to a payment",
    tagKey = "press"
)
PantrixText(text = pressed ?: "Press a stage")

private val FUNNEL_STEPS = listOf(
    FunnelStage("visits", "Visits", 3000),
    FunnelStage("signups", "Sign-ups", 1240),
    FunnelStage("trials", "Trials", 520),
    FunnelStage("paid", "Paid", 310)
)

A stage that widens

A stage can be larger than the one before it: more people called than leads that came in. The chart changes neither the order nor the number; that stage widens instead of narrowing, and its share goes over a hundred per cent.

The last stage is too narrow for its words, so its name and its value stand beside it.

PantrixFunnelChart(
    stages = listOf(
        FunnelStage("leads", "Leads", 800),
        FunnelStage("calls", "Calls", 950),
        FunnelStage("offers", "Offers", 300),
        FunnelStage("won", "Sales", 40)
    ),
    description = "From a lead to a sale: more calls than leads",
    tagKey = "widening"
)

Your own colours

The stages' own colours: a role of the theme, lighter from stage to stage. Each FunnelStage carries its own colour; a stage given none takes the chart colour of its place.

val tone = PantrixTheme.colors.primary.color
PantrixFunnelChart(
    stages = FUNNEL_STEPS.mapIndexed { place, stage ->
        FunnelStage(stage.key, stage.name, stage.value, tone.copy(alpha = 1f - place * 0.2f))
    },
    description = "The stages a visit goes through until it comes to a payment, in one colour",
    tagKey = "own_colors"
)

private val FUNNEL_STEPS = listOf(
    FunnelStage("visits", "Visits", 3000),
    FunnelStage("signups", "Sign-ups", 1240),
    FunnelStage("trials", "Trials", 520),
    FunnelStage("paid", "Paid", 310)
)

Export

export = ChartExport(...) puts an export button over the chart: press it and choose the kind (PNG, SVG or PDF). The chart makes the file and hands it to onExport; below, its name and size show, and a PNG's picture, and "Save the file" hands it over in the platform's way.

The file has the stages, their values and their rates.

var file by remember { mutableStateOf<ChartExportFile?>(null) }
PantrixFunnelChart(
    stages = FUNNEL_STEPS,
    description = "The stages a visit goes through until it comes to a payment",
    tagKey = "exported",
    export = ChartExport(fileName = "visit-to-payment") { file = it }
)
ExportedFile(file, tagKey = "exported")

private val FUNNEL_STEPS = listOf(
    FunnelStage("visits", "Visits", 3000),
    FunnelStage("signups", "Sign-ups", 1240),
    FunnelStage("trials", "Trials", 520),
    FunnelStage("paid", "Paid", 310)
)

API

stages

A funnel: the stages of something that fewer and fewer get through, one under another, each as wide as the number that reached it. It shows where the others were lost: the visitors who signed up, the sign-ups who tried, the trials who paid.

ChartStyle

A chart's geometry: how tall it is where nothing says, how thick its lines and how large its marks are, and the room between its parts; and whether its fills have textures besides their colours.

ChartColors

What a chart is painted with, for a chart that does not take the theme's colours: a colour that is set is used, and one that is left out stays the theme's.

Accessibility

• Screen reader. First the chart's description, then each stage in its order: its name, its value and its shares. A share of the first stage written alone is read bare; otherwise each share is read with what it is a share of.