On this page

Charts

RunwayChart

Which allowances will run out before they reset. Every row is a strip of time cells shaded by the projected use, with a dot where the allowance runs out and hatching until it resets.

When to use it #

Use RunwayChart for limits that reset: API quotas, GPU hours, a usage cap per seat. Each row has its own window, a projection of cumulative use, and optionally when it runs out and when it resets. The chart shades each cell by the projected share (breaks, tone), marks the moment the allowance runs out, hatches the locked time until the reset, and draws a Now line.

To see how one allowance moved over time, use LineChart with a time axis (see time scales): it plots one value per moment, while the runway compares many allowances on the same dates.

Import #

Terminal
npm i tally-charts
app/quotas.tsx
import { RunwayChart, runwayForecast } from 'tally-charts'
import 'tally-charts/theme.css'

Examples #

Rows are built by spreading runwayForecast over each window: it adds the projection, runsOutAt and resetAt. The now and the windows are fixed ISO strings, so the page renders the same on every request. A row with disconnected is muted and has no forecast. runwayForecast is imported from tally-charts/core, whose functions a server component can call, and every prop is serializable.

API quotas: which keys run out before they reset
View of API quotas: which keys run out before they reset
Checkout API
Runs out Thu 15:06 Resets Sun 00:00
Search indexer
~51% at reset Resets Fri 12:00
Mailer
~95% at reset Resets Tue 00:00
Image resize
Runs out Thu 15:30 Resets Mon 00:00
Reports export
Runs out Wed 18:53 Resets Sat 06:00
Webhook relay
Disconnected
  • Projected useunder 25, 50, 75, 100%
  • Runs out
  • Locked until reset
  • Reset
  • New window, no forecast
API quotas: which keys run out before they reset
NameDetailRuns outResetsProjected at resetStatus
Checkout APIPaymentsThu 15:06Sun 00:00100%Runs out Thu 15:06, Resets Sun 00:00
Search indexerCatalogno valueFri 12:0051%~51% at reset, Resets Fri 12:00
MailerGrowthno valueTue 00:0095%~95% at reset, Resets Tue 00:00
Image resizeCatalogThu 15:30Mon 00:00100%Runs out Thu 15:30, Resets Mon 00:00
Reports exportFinanceWed 18:53Sat 06:00100%Runs out Wed 18:53, Resets Sat 06:00
Webhook relayPlatformno valueno valueno valueDisconnected

activeId is the highlighted row, and onActiveChange reports hover and keyboard changes. Here both live in useState, so the buttons outside the chart move the highlight too, and onSelect with selectedId makes the rows a listbox. Functions and state make this a client component.

GPU hours per team, with the highlighted row controlled from outside
View of GPU hours per team, with the highlighted row controlled from outside

Props #

NameTypeDefaultRequiredDescription
activeIdstring | null—No

The highlighted row (hover or keyboard cursor). Pass it to control the highlight, e.g. to link it with another view; null for none. Leave it out to let the chart keep its own.

aria-labelledbystring—No

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

breaksreadonly number[][0.25, 0.5, 0.75]No

Ascending level edges as shares. Default [0.25, 0.5, 0.75]: four levels. 1–4 edges.

cellstring | number'6h'No

Cell length: '30m', '6h', '1d' or ms. Default '6h'.

chartIdstringReact's `useId`No

Stable base for the element ids. Default: React's useId.

classNamestring—No

Class on the root element.

dataTableboolean | DataTableOptionstrueNo

A visually hidden table of the rows for screen readers. Default true.

descriptionstring—No

Accessible description, usually the takeaway sentence.

domainreadonly [TimeInput, TimeInput]—Yes

Time span of the strips.

emptyReactNode"No data"No

Rendered instead of the rows when there are none or the domain is invalid. Default "No data".

initialWidthnumber960 (the columns layout)No

Width before the first measurement and on the server. Default 960 (the columns layout).

labelWidthnumber200No

Label column width in px in the columns layout. Default 200.

layout'auto' | 'columns' | 'stacked''auto'No

'auto' stacks the rows when the strip would be under 240 px. Default 'auto'.

legendbooleantrueNo

Default true.

nowTimeInput—Yes

The present: the Now line, and the reference for "Fri 03:24" versus "Oct 21 09:21".

onActiveChange(id: string | null, row: RunwayRow | null) => void—No

Called when hover, the keyboard or Escape changes the highlighted row.

onSelect(id: string, row: RunwayRow) => void—No

Click, Enter or Space on a row. With it, the rows are a listbox; without, a plain list.

rowsreadonly RunwayRow[]—Yes

One strip per row, in this order.

selectedIdstring | null—No

The selected row, marked with data-ch-selected; with onSelect also aria-selected.

status(row: RunwayRow, facts: RunwayFacts) => ReactNode—No

Custom status per row: return undefined to keep the default, null for none. A string is also the table's Status and part of the option's name. A row's own status wins.

styleCSSProperties—No

Style on the root element.

titlestring—No

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

toneTone'neutral'No

Sequential tone of the levels and the legend. Default 'neutral'.

zoneTimeZone'utc'No

Zone of the day boundaries and the dates. Default 'utc'.

runwayForecast #

runwayForecast turns one window into the fields of a row. Spread the result into the row next to the id and label: { id, label, ...runwayForecast({ used, windowStart, resetAt, now }) }. It returns projection, runsOutAt (only when the allowance runs out before resetAt), resetAt and the numbers usedAtReset, paceRatio, elapsed and lockedMs. The pace is the observed one unless you pass pace, a share per day.

ParameterTypeDefaultRequiredDescription
inputRunwayForecastInput—Yes—

Returns RunwayForecast

Rows and options #

A row is { id, label, icon?, sublabel?, projection?, runsOutAt?, resetAt?, disconnected?, status? }. projection is a list of { at, used } points, used from 0 to 1, with a straight line between the points; a row without a projection has no forecast. Cells before the first point take that point's value, so start the domain at now or include the history.

  • domain and now are dates, epoch milliseconds or ISO strings. An invalid domain, or no rows, shows empty ("No data" by default).
  • cell is the length of one cell: '30m', '6h' (the default), '1d' or a number of milliseconds. A strip has at most 200 cells; a cell too short for the domain draws the first 200 and warns in development ("use a longer cell").
  • breaks are 1 to 4 ascending level edges as shares, [0.25, 0.5, 0.75] by default. n edges make n + 1 levels.
  • tone (default 'neutral') colors the levels and the legend and is always applied: a --ch-seq-base set on an ancestor does not reach this chart.
  • layout is 'auto', 'columns' or 'stacked'. 'auto' stacks the rows when the strip would be under 240px. On the server there is no measurement, so initialWidth (default 960, which renders columns) decides; labelWidth (default 200) is the label column in pixels.
  • zone is 'utc' by default and sets the day boundaries and the dates in the status. 'local' can differ between the server and the client.

How cells are drawn #

Every cell is decided at its midpoint, in this order:

  • Before the run-out, with a forecast: a level from the projection at that moment, binned by breaks.
  • The cell that holds the run-out: the "runs out" cell, and the dot sits in it.
  • After the run-out and before the reset: locked, drawn hatched.
  • After the reset, or with no forecast: empty.

The cells carry that decision as data-ch-state: level, runs-out, locked or empty (see below). The levels use the sequential ramp --ch-seq-1 to --ch-seq-5, see Theming.

Status text and dates #

The default status has two lines. The first is Runs out <date> when the allowance runs out, ~N% at reset when it does not (the projected share at the reset), or No forecast when the row has no projection. The second is Resets <date>. A row with disconnected reads Disconnected.

Dates are relative to now:

  • Within six days of now: weekday and time, Fri 03:24.
  • Later in the domain: month, day and time, Oct 21 09:21.
  • Past the end of the domain: month and day only, Nov 9, with → after a reset.

The built-in strings ("Now", "reset", "Runs out", the legend and the table headers) are English. To change what you can, pass status, legend={false} or your own title. A row's own status wins over the status function, and a string from either is also the table's Status.

Parts and attributes #

These names are part of the public surface (see Stability), so you can select them with [data-ch-part="…"].

  • Parts: runway, runway-axis, runway-now-label, runway-head-row, runway-rows, runway-row, runway-label, runway-icon, runway-name, runway-strip, runway-cell, runway-now, runway-reset, runway-reset-label, runway-dot, runway-status and runway-status-line.
  • data-ch-layout: columns or stacked.
  • data-ch-state on a cell: level, runs-out, locked or empty.
  • data-ch-focus: the row the keyboard cursor is on, while the listbox has focus (only with onSelect).
  • On a row: data-ch-active, data-ch-muted (a disconnected row), data-ch-selectable and data-ch-selected.

Keyboard and screen readers #

Without onSelect the rows are a plain list of listitems: there is no tab stop and no keys. With onSelect the rows container is a listbox and one tab stop. The focused row is aria-activedescendant, and real focus stays on the container. Tabbing in resumes at the existing cursor (set by earlier keys or a click), else at the selected row, else at the first. Hovering a row highlights it but does not move the cursor; pressing a row moves the cursor there.

↑ and ↓ move one row, Home and End go to the first and last, and PageUp and PageDown move five. Enter or Space selects the focused row. Esc clears the active row, and only when one is active, so an enclosing dialog still closes. Keys with Alt, Ctrl or Cmd pass through. The cursor follows its row by id when rows change, and falls back to the first row if that row is gone.

Screen readers get a list (or, with onSelect, a listbox) named by title or aria-labelledby and described by description. Each row is announced by its label followed by its status, such as “Work account Runs out Fri 03:24 Resets Mon 09:21”; with onSelect each is an option with aria-selected, named from those two parts. The strips, the time axis and the legend swatches are hidden from assistive technology, and icons are hidden too. A visually hidden data table has the name, detail text, run-out, reset, projected share at reset and status of every row (dataTable renames it or turns it off). A custom status replaces the text that is read, and null leaves the row with its label only. A disconnected row reads “Disconnected”.

The full model is in the accessibility guide.