On this page

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 #

Terminal
npm i tally-charts
app/replies.tsx
import { 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.

Hours to the first reply, one dot per ticket
View of Hours to the first reply, one dot per ticket
Hours to the first reply, one dot per ticket
TicketHours
#41001 h
#41011.9 h
#41022.3 h
#41031.7 h
#41041.5 h
#41051.9 h
#41062.6 h
#41071.8 h
#41081.5 h
#41092.4 h
#41101.9 h
#41111.7 h
#41125.8 h
#41132.6 h
#41142.2 h
#41158.4 h
#41166.2 h
#41171.1 h
#41185.5 h
#41192.6 h
#41205.8 h
#41213.6 h
#41227.2 h
#41232.6 h
#41241.2 h
#41251.3 h
#41261.2 h
#41271.5 h
#41282.7 h
#41299.4 h
#41303.6 h
#41312.3 h
#41323.4 h
#41332.9 h
#41343.6 h
#41352.4 h
#41363.9 h
#41371.5 h
#41384 h
#41392.9 h
#41400.4 h
#41413 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.

Open invoices by days overdue, colored by age
View of Open invoices by days overdue, colored by age

When the dots are crowded they shrink, down to a minimum size (minRadius), and then the chart warns in development.

Props #

NameTypeDefaultRequiredDescription
activeIdId | null—No—
animateboolean—No—
aria-labelledbystring—No

Id of an element that names the chart; it wins over title for the name.

axisTickSpec | 'none'6No

Value axis ticks, or 'none'. Default 6.

axisFormatAxisFormat`format`No

Axis label format. Default: format.

binWidthnumbera nice step that gives about 50 binsNo

Bin width in value units. Default: a nice step that gives about 50 bins.

calloutIdId—No

Pin a callout with a stem to this item id.

chartIdstring—No

Prefix for pattern and mask ids. React's useId is only unique within one root, so set this when charts render in several React roots on one page.

childrenReactNode—No—
classNamestring—No—
datareadonly D[]—Yes—
dataTableboolean | DataTableOptionstrueNo

Hidden data table for screen readers: true, false, or { caption, columns } to set its caption and rename column headers. Default true.

descriptionstring—No

Accessible description, usually the takeaway sentence.

dimInactiveboolean—No—
domainreadonly [number, number]the data range including zero, rounded to nice ticksNo

Value domain. Default: the data range including zero, rounded to nice ticks.

emptyReactNode"No data"No

Rendered instead of the plot when data is an empty array. Default "No data".

formatFormatSpec'number'No

Default 'number'.

heightnumber240 unless `aspectRatio` is setNo

Height in px. Default 240 unless aspectRatio is set.

idAccessor<D, Id>the data indexNo

Passed to onSelect, onActiveChange and calloutId. Default: the data index.

initialWidthnumber640No

Width used for server rendering and the first client render. Default 640.

keyboardHintstring"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 onSelect. A custom text is used as is. Set it to translate the text; "" turns it off.

labelAccessor<D, string>—No

Item name for announcements and the default tooltip, e.g. "#5819".

marginPartial<Margin>—No—
maxRadiusnumber6No

Default 6.

minRadiusnumber2No

Default 2.

onActiveChange(id: Id | null, point: ChartPoint<D> | null) => void—No

Called with the new active id, and its point; point.datum is the row from data.

onSelect(id: Id, point: ChartPoint<D>) => void—No

Called on click, Enter or Space; point.datum is the row from data.

segments(d: D, i: number) => readonly TooltipSegment[]—No

Custom tooltip segments per item.

styleCSSProperties—No—
targetnumber | { value: number; label?: string }—No—
titlestring—No

Accessible name of the chart; also the default caption of the data table.

toneByThresholds | ((d: D, i: number) => Tone)'accent'No

Tone per item: a thresholds() result or a function. Default 'accent'.

tooltipChartTooltip<D>trueNo

Tooltip on hover and focus: true for the default pill, or a function that renders the content for a point (point.datum is your row). Default true.

valueAccessor<D, number>—Yes

The binned value, e.g. margin.

widthnumber—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.