Charts
DotHistogram
A histogram that keeps the items. Each row of your data is one dot, dots with similar values stack in a bin, and the tallest stacks show where most items sit. You can still point at a single dot: it has a name, a tooltip and an announcement of its own.
When to use it #
Use DotHistogram for the distribution of one value across many items, when the individual items matter as much as the shape: tickets by hours to the first reply, invoices by days overdue, jobs by margin. binWidth sets the width of a bin and domain the range. target draws a reference line with a label, and calloutId pins a pill to one item. toneBy colors each dot, with a thresholds() result for named bands (which also puts the band in the tooltip and the data table) or a function for anything else.
If the same items are measured more than once and you want to compare the measures, use StripPlot: one row of dots per measure, with a median. If you want totals per period rather than items, use WaffleColumns: one column of dots per period, where a dot stands for a unit of the total.
Import #
npm i tally-chartsimport { DotHistogram } from 'tally-charts'
import 'tally-charts/theme.css'Examples #
With no toneBy, every dot has the accent tone. value and label are field names, binWidth and domain fix the bins, and target marks the 4-hour goal.
| Ticket | Hours |
|---|---|
| #4100 | 1 h |
| #4101 | 1.9 h |
| #4102 | 2.3 h |
| #4103 | 1.7 h |
| #4104 | 1.5 h |
| #4105 | 1.9 h |
| #4106 | 2.6 h |
| #4107 | 1.8 h |
| #4108 | 1.5 h |
| #4109 | 2.4 h |
| #4110 | 1.9 h |
| #4111 | 1.7 h |
| #4112 | 5.8 h |
| #4113 | 2.6 h |
| #4114 | 2.2 h |
| #4115 | 8.4 h |
| #4116 | 6.2 h |
| #4117 | 1.1 h |
| #4118 | 5.5 h |
| #4119 | 2.6 h |
| #4120 | 5.8 h |
| #4121 | 3.6 h |
| #4122 | 7.2 h |
| #4123 | 2.6 h |
| #4124 | 1.2 h |
| #4125 | 1.3 h |
| #4126 | 1.2 h |
| #4127 | 1.5 h |
| #4128 | 2.7 h |
| #4129 | 9.4 h |
| #4130 | 3.6 h |
| #4131 | 2.3 h |
| #4132 | 3.4 h |
| #4133 | 2.9 h |
| #4134 | 3.6 h |
| #4135 | 2.4 h |
| #4136 | 3.9 h |
| #4137 | 1.5 h |
| #4138 | 4 h |
| #4139 | 2.9 h |
| #4140 | 0.4 h |
| #4141 | 3 h |
import { DotHistogram } from 'tally-charts'
import type { ExampleMeta } from '../types'
export const meta = {
id: 'dot-histogram/first-reply-times',
title: 'Hours to the first reply, one dot per ticket',
rscSafe: true,
} satisfies ExampleMeta
const hours = [
1, 1.9, 2.3, 1.7, 1.5, 1.9, 2.6, 1.8, 1.5, 2.4, 1.9, 1.7, 5.8, 2.6, 2.2, 8.4, 6.2, 1.1, 5.5, 2.6,
5.8, 3.6, 7.2, 2.6, 1.2, 1.3, 1.2, 1.5, 2.7, 9.4, 3.6, 2.3, 3.4, 2.9, 3.6, 2.4, 3.9, 1.5, 4, 2.9,
0.4, 3,
]
const tickets = hours.map((h, i) => ({ ticket: `#${4100 + i}`, hours: h }))
// Props stay serializable (accessor strings, no functions): the page is a server component.
export default function FirstReplyTimes() {
return (
<DotHistogram
title={meta.title}
description="Of 42 tickets, 35 got a first reply within the 4-hour target and 7 took longer. The slowest took 9.4 hours."
data={tickets}
value="hours"
label="ticket"
format="hours"
binWidth={0.5}
domain={[0, 10]}
target={{ value: 4, label: 'Target 4 h' }}
/>
)
}
toneBy takes a thresholds() result: the breaks, a tone for each band and a name for each band. bands.legend(values) gives the legend items with counts. A result of thresholds() has methods, so this example is a client component.
'use client'
import { DotHistogram, Legend, thresholds } from 'tally-charts'
import type { ExampleMeta } from '../types'
export const meta = {
id: 'dot-histogram/invoice-days-overdue',
title: 'Open invoices by days overdue, colored by age',
rscSafe: false,
} satisfies ExampleMeta
const overdue = [
95, 51, 32, 9, 29, 25, 14, 65, 81, 8, 31, 22, 13, 21, 33, 7, 11, 14, 24, 93, 27, 59, 2, 2, 27, 8,
25, 33, 7, 42, 21, 7, 4, 24, 18, 3, 5, 87, 62, 43, 12, 29, 43, 95, 34, 16, 37, 89, 12, 31, 34, 34,
31, 8, 26, 32,
]
const invoices = overdue.map((days, i) => ({ number: `INV-${2040 + i}`, days }))
const ages = thresholds(
[15, 30, 60],
['gain', 'accent-soft', 'warn', 'loss'],
['Under 15 days', '15 to 29 days', '30 to 59 days', '60 days or more'],
)
// 'use client': thresholds() returns an object with methods, which a server component cannot pass.
export default function InvoiceDaysOverdue() {
return (
<div>
<Legend shape="dot" items={ages.legend(overdue)} />
<DotHistogram
title={meta.title}
description="Of 56 open invoices, 18 are under 15 days overdue and 8 are 60 days or more. The oldest is 95 days."
data={invoices}
value="days"
label="number"
toneBy={ages}
binWidth={5}
domain={[0, 100]}
/>
</div>
)
}
When the dots are crowded they shrink, down to a minimum size (minRadius), and then the chart warns in development.
Props #
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
activeId | Id | null | — | No | — |
animate | boolean | — | No | — |
aria-labelledby | string | — | No | Id of an element that names the chart; it wins over |
axis | TickSpec | 'none' | 6 | No | Value axis ticks, or 'none'. Default 6. |
axisFormat | AxisFormat | `format` | No | Axis label format. Default: |
binWidth | number | a nice step that gives about 50 bins | No | Bin width in value units. Default: a nice step that gives about 50 bins. |
calloutId | Id | — | No | Pin a callout with a stem to this item id. |
chartId | string | — | No | Prefix for pattern and mask ids. React's |
children | ReactNode | — | No | — |
className | string | — | No | — |
data | readonly D[] | — | Yes | — |
dataTable | boolean | DataTableOptions | true | No | Hidden data table for screen readers: |
description | string | — | No | Accessible description, usually the takeaway sentence. |
dimInactive | boolean | — | No | — |
domain | readonly [number, number] | the data range including zero, rounded to nice ticks | No | Value domain. Default: the data range including zero, rounded to nice ticks. |
empty | ReactNode | "No data" | No | Rendered instead of the plot when |
format | FormatSpec | 'number' | No | Default 'number'. |
height | number | 240 unless `aspectRatio` is set | No | Height in px. Default 240 unless |
id | Accessor<D, Id> | the data index | No | Passed to onSelect, onActiveChange and |
initialWidth | number | 640 | No | Width used for server rendering and the first client render. Default 640. |
keyboardHint | string | "Use arrow keys to move between points, Home and End for first and last, Escape to clear.", plus " Press Enter to select." while the active point (or the first, before one is active) can be selected with `onSelect` | No | Instructions read with the chart when it takes keyboard focus. Default: "Use arrow keys to move between points, Home and End for first and last, Escape to clear.", plus " Press Enter to select." while the active point (or the first, before one is active) can be selected with |
label | Accessor<D, string> | — | No | Item name for announcements and the default tooltip, e.g. "#5819". |
margin | Partial<Margin> | — | No | — |
maxRadius | number | 6 | No | Default 6. |
minRadius | number | 2 | No | Default 2. |
onActiveChange | (id: Id | null, point: ChartPoint<D> | null) => void | — | No | Called with the new active id, and its point; |
onSelect | (id: Id, point: ChartPoint<D>) => void | — | No | Called on click, Enter or Space; |
segments | (d: D, i: number) => readonly TooltipSegment[] | — | No | Custom tooltip segments per item. |
style | CSSProperties | — | No | — |
target | number | { value: number; label?: string } | — | No | — |
title | string | — | No | Accessible name of the chart; also the default caption of the data table. |
toneBy | Thresholds | ((d: D, i: number) => Tone) | 'accent' | No | Tone per item: a |
tooltip | ChartTooltip<D> | true | No | Tooltip on hover and focus: |
value | Accessor<D, number> | — | Yes | The binned value, e.g. margin. |
width | number | — | No | Fixed width in px; turns off container measuring. |
Keyboard and screen readers #
DotHistogram is built on Chart, so it follows the same keyboard model as the other charts: it is a single tab stop, and tabbing in shows the first dot with its tooltip and announces it. Its dots form stacks, so it moves in two dimensions: ← and → walk from bin to bin, ↑ and ↓ walk up and down the stack in a bin. Home and End jump to the first and last point, Enter or Space selects the active point when the chart has onSelect, and Esc clears the active point. Esc is only consumed when a point is active, so an enclosing dialog still closes. The widget’s description ends with a keyboard hint (“Use arrow keys to move between points, Home and End for first and last, Escape to clear.”, plus “Press Enter to select.” with onSelect); keyboardHint replaces it, for example to translate it, and keyboardHint="" turns it off.
Screen readers get the chart title and description, then an announcement for each dot the keyboard moves to. With toneBy set to thresholds() the band is read as the series and the position counts within the band, as in “Critical, 1 of 6, #5600, 3.1%”: the band, the position in it, the item’s label and its value. Without bands, or with a function, the series is left out. A visually hidden data table follows the chart with the columns Item and Value, named after the label and value field when they are strings, and a Group column when toneBy is a thresholds() result. dataTable renames the caption and headers, or turns it off.
The SVG and the HTML overlay are aria-hidden, so a target line and a calloutId pill say nothing to a screen reader. Put the same facts in the title, the description or the data, as both examples do with their counts.
The full model is in the accessibility guide.