On this page

Guides

Thresholds

A threshold turns a number into a category: a page load of 3.1 s is "Needs improvement", a margin of 9% is "Critical". thresholds() builds those categories once, and the same result colors a ZoneMeter, counts a Legend and tones the dots of a DotHistogram, so a value gets the same color everywhere. heatmapLevel() does the matching job for a Heatmap.

Building thresholds #

thresholds(breaks, tones, labels, options) takes the ascending break values, a tone for each bin and a label for each bin. There is one more tone and one more label than there are breaks: two breaks make three bins. A spec that does not fit, or breaks that are not finite and strictly ascending, throws, because it is a mistake in the code rather than in the data.

import { thresholds } from 'tally-charts'

// Largest contentful paint in seconds: 2 breaks, 3 bins.
const lcp = thresholds(
  [2.5, 4],
  ['gain', 'warn', 'loss'],
  ['Good', 'Needs improvement', 'Poor'],
)

lcp.indexOf(3.1) // 1
lcp.toneOf(3.1) // 'warn'
lcp.toneOf('n/a') // undefined
lcp.indexOf('n/a') // -1

The result carries the plain data and three helpers. bins lists the bins as { label, tone, min, max }; the first starts at -Infinity and the last ends at Infinity. indexOf(value) is the index of the bin that holds a value, or -1 for a value that is missing or not a number. toneOf(value) is the tone of that bin. legend(values) counts how many of the values fall into each bin and returns entries for a Legend.

Which bin holds a value on a break #

The inclusive option decides what happens to a value that is exactly on a break. With 'lower', the default, a bin is [min, max): the value belongs to the bin above the break. With 'upper' a bin is (min, max]: the value belongs to the bin below it, which is how Core Web Vitals count their tiers.

Take an LCP of exactly 2.5 s against the breaks [2.5, 4]. With inclusive: 'lower' it is "Needs improvement", because 2.5 starts the second bin. With inclusive: 'upper' it is "Good", because 2.5 ends the first one. The same goes for 4 s: "Poor" with 'lower', "Needs improvement" with 'upper'. Values that are not on a break fall in the same bin either way.

const strict = thresholds([2.5, 4], tones, labels) // 'lower'
const vitals = thresholds([2.5, 4], tones, labels, { inclusive: 'upper' })

strict.toneOf(2.5) // 'warn' (Needs improvement)
vitals.toneOf(2.5) // 'gain' (Good)

In ZoneMeter, Legend and DotHistogram #

Pass the result to ZoneMeter as zones: the track draws one zone per bin and the marker sits at the value, which the screen reader hears together with the label of its bin. ZoneMeter reads inclusive too, so a value on a break lands in the bin your thresholds() call says. Pass it to DotHistogram as toneBy to tone each dot by its bin, and give Legend the result of legend(values) with shape="dot" for the swatches and counts.

Page loads by largest contentful paint, colored by tier
View of Page loads by largest contentful paint, colored by tier
  • Good13
  • Needs improvement7
  • Poor3
Page loads by largest contentful paint, colored by tier
ItemLcpGroup
no value1.2Good
no value1.4Good
no value1.5Good
no value1.7Good
no value1.8Good
no value1.9Good
no value2Good
no value2.1Good
no value2.2Good
no value2.3Good
no value2.4Good
no value2.5Good
no value2.5Good
no value2.6Needs improvement
no value2.8Needs improvement
no value3Needs improvement
no value3.2Needs improvement
no value3.5Needs improvement
no value3.8Needs improvement
no value4Needs improvement
no value4.3Poor
no value4.8Poor
no value5.4Poor

Both meters show the same value, 2.5 s. The first uses inclusive: 'upper' and reads "Good"; the second uses the default and reads "Needs improvement". The two loads of exactly 2.5 s in the histogram are toned and counted as Good. The thresholds() result has methods, so it can only be passed from a client component. A Server Component can give ZoneMeter the plain { bins, inclusive } instead; see Server Components.

Parameters of thresholds #

ParameterTypeDefaultRequiredDescription
breaksreadonly number[]—Yes—
tonesreadonly Tone[]—Yes—
labelsreadonly string[]—Yes—
optionsThresholdOptions{}No—

Returns Thresholds

Matching a Heatmap #

A Heatmap bins its values by breaks and paints each cell with a sequential level from 1 to 5. Its own legend already matches. When you draw the legend yourself, with a standalone Legend somewhere else on the page, heatmapLevel(value, breaks) gives the level the heatmap would paint that value with, so the swatches use the same colors. It returns 0 for a missing or non-numeric value.

The breaks are cleaned the way Heatmap cleans them: sorted, deduplicated and cut to the first four, which make the five bins. Four bins use the levels 1, 2, 4 and 5, and fewer bins spread over the range with the ends pinned, so do not work the levels out by hand. Take one value from each bin, ask heatmapLevel for its level and set it as the level of a Legend item. These are plain numbers, so the call also works in a Server Component.

Support tickets by day and category, with a legend of the same bins
View of Support tickets by day and category, with a legend of the same bins

Parameters of heatmapLevel #

ParameterTypeDefaultRequiredDescription
valueunknown—Yes—
breaksreadonly number[]—Yes—

Returns SeqLevel | 0