mailinapp
Documentation menu

Histogram block

Automatic binning of raw values into readable ranges — hand it individual numbers, not pre-counted buckets, and it works out the distribution for you.

How it works

Unlike every sibling chart in this family, a histogram has no category-or-series authoring shape at all: the row-list is a single Value column of raw numbers, one per row — a test score per student, an order total per transaction, a response time per request. Binning into ranges happens at render time, not authoring time — you never type a range or a count yourself. Once binned, a histogram is drawn and rendered exactly like a single-series bar chart (it reuses the bar chart's own raster pipeline internally), so it inherits the same rendered-PNG-plus-always-visible-data-table contract every chart in this family commits to: the image is never the only place the bucket counts live.

You control roughly how many bins to aim for via Number of bins (2–20). The block divides the range from your data's minimum to its maximum into that many equal-width buckets and counts how many authored values fall in each one. If every value you typed is identical, the range is zero and there's nothing to divide — rather than drawing your requested bin count as one real bar and the rest as empty ones, the histogram collapses to a single bin holding every value, since a distribution with exactly one distinct value is inherently one bar, not N-1 empty buckets flanking it.

The data table beneath the image lists every bin's exact range (formatted as "start–end") alongside its count — the one place to read precise bucket boundaries and counts together, since the image communicates the shape of the distribution at a glance but doesn't label every bar once bin count climbs toward the upper end of the range.

Blank or non-numeric cells in the Value column are dropped before binning (an empty cell isn't a real zero); up to 500 authored values are read in, generous for anything typed by hand.

This block is authored-rows only — it has no data-source-binding or campaign-response-binding mode. See Binding charts to real data for which four chart types do support binding.

Configurable fields:

  • Chart title — shown above the image.
  • Values — the row-list, a single Value column, one raw number per row.
  • Number of bins — 2 to 20, how many equal-width buckets to aim for.
  • Bar color — overrides the default palette color for every bin.
  • Background color, padding, border, border radius on the card.
  • Independent color/font-size pairs for the title and the legend/table text.

Examples

Subject

This week's order value spread

A quiz results digest can histogram every student's raw score out of 100, immediately showing whether the class clustered around a passing grade or split into two groups. A support-ops report might histogram response times in minutes across the week's tickets, making it obvious at a glance whether most tickets close fast with a long tail of outliers, or cluster near an SLA boundary. An e-commerce recap can histogram order values to see the natural price bands customers are buying in, without pre-deciding what those bands should be — the block works that out from the raw totals itself.

What the static fallback looks like

<div style="margin:12px 0;padding:16px;background-color:#ffffff;border-radius:8px">
  <p style="margin:0 0 8px;font-weight:600;font-size:15px;color:#111827">Quiz scores</p>
  <img src="https://mailinapp.com/api/analytics/chart?d=eyJ0eXBlIjoi...&s=3f9a2b1c..." width="560" height="280"
       alt="Histogram: 60–68: 3, 68–76: 5, 76–84: 9, 84–92: 7, 92–100: 4"
       style="display:block;max-width:100%;height:auto;margin:8px 0" />
  <table style="width:100%;border-collapse:collapse;margin-top:4px">
    <tr>
      <th style="text-align:left;padding:4px 8px;font-weight:600;font-size:12px;color:#6b7280">Category</th>
      <th style="text-align:left;padding:4px 8px;font-weight:600;font-size:12px;color:#6b7280">Count</th>
    </tr>
    <tr>
      <td style="text-align:left;padding:4px 8px;font-size:12px;color:#6b7280">76–84</td>
      <td style="text-align:left;padding:4px 8px;font-size:12px;color:#6b7280">9</td>
    </tr>
  </table>
</div>

Each bin's exact range and count is a plain table row — the same numbers the alt text summarizes and the bars visualize.

Related