On this page

Guides

Time scales

LineChart, Area and the other time-based marks put dates on the x axis. This page covers what counts as a date, what happens to one that is not, and which time zone the axis speaks. Two helpers, toTime and toNumber, show the rules the charts apply to your data.

Putting dates on the x axis #

Pass a time scale spec as x: x={{ type: 'time', field: 'date' }}. LineChart takes the same spec; with Chart you give it to the x prop and draw Line, Band or Area inside. A value can be a Date, epoch milliseconds or an ISO 8601 string, and a date-only string such as '2026-01-05' is UTC midnight. Rows are sorted by date, so the data does not have to arrive in order.

Daily sign-ups with one unreadable date
View of Daily sign-ups with one unreadable date
Daily sign-ups with one unreadable date
DateSign-ups
Jan 542
Jan 648
Jan 751
Jan 847
Jan 1063
Jan 1158
Jan 1266

The row 'not a date' can not be read, so it is skipped and the line breaks instead of joining its neighbours across the gap. A chart prints one warning in development for all the rows it skipped, and the point is not drawn or reachable by pointer or keyboard. An epoch outside the JavaScript Date range (±8.64e15 ms) counts as invalid too, and such a date formats as an empty string. See LineChart for the series options.

Domain and ticks #

The domain is inferred from the data and rounded out to tick boundaries. A single date is padded by a day on each side. An explicit domain is kept as given unless you also set nice: true, and a domain with a value that is not a date is ignored with a warning. A date outside an explicit domain is skipped just like an invalid one. Ticks snap to calendar units from seconds to decades and are labelled in several scales ("Jan 2026", "Feb", …, "2027"). A tick whose label repeats the one before it is dropped.

To choose the labels yourself, give the axis a date format: 'day', 'month', 'quarter', 'year', or any Intl.DateTimeFormatOptions such as { month: 'short', day: 'numeric' }. In LineChart that is xAxisFormat, and the tooltip headers and the data table use it too. Labels follow the locale of the ChartsProvider (see Hooks and providers); Formatting covers createDateFormatter for the same thing in code.

UTC or local time #

zone is 'utc' by default. Ticks and labels then fall on UTC calendar boundaries, so the server and the browser draw the same chart. 'local' uses the viewer's zone, which can differ between the two and cause a hydration mismatch, so prefer 'utc' for server rendering.

Line, Band, Area, Region, Target (with x as a date), Grid, Axis and NearestPointer work on a time scale. Bars and ColumnHighlight need a band scale, so on a time scale they warn instead of drawing.

toTime and toNumber #

The charts read your data with two small functions, and you can call them yourself to check what a chart will make of a value. Neither is exported from the main entry: import them from tally-charts/core, which has no React in it.

import { toNumber, toTime } from 'tally-charts/core'

toTime('2026-01-05') // 1767571200000 (UTC midnight)
toTime(new Date(0)) // 0
toTime('not a date') // undefined

toNumber('42.5') // 42.5
toNumber('') // NaN, not 0
toNumber(null) // NaN

toTime returns epoch milliseconds, or undefined when the value is not a date. That covers a Date that is invalid, a number outside ±8.64e15, a string that Date.parse rejects and any other type. toNumber is the strict counterpart for values: a number passes through, a non-blank string is parsed, and everything else (null, undefined, '', booleans, objects) is missing and becomes NaN instead of 0, so a gap in the data does not draw as a zero.

Parameters #

ParameterTypeDefaultRequiredDescription
valueunknown—Yes—

Returns number | undefined

ParameterTypeDefaultRequiredDescription
rawunknown—Yes—

Returns number