Customizing D3 Time Scales for Irregular Timestamps

Your time-series chart shows ticks that fall between actual data points, labels that clip at the chart edge, and line segments that compress huge gaps into the same pixel width as dense clusters.

This is a scale-configuration problem, not a data problem. The fixes build directly on scales and axes configuration, which covers how D3 binds a continuous domain to discrete pixels.

The confusion arises because a time scale looks like it should “know” where your data points are, but it does not. scaleTime is a linear interpolator over milliseconds: it knows only the first and last timestamp and stretches everything in between uniformly across the pixel range. The tick generator then asks for calendar-aligned round numbers — midnights, hour marks, month boundaries — that have no relationship to where your samples actually fall. On a uniform series those calendar ticks happen to line up; on an irregular series they land in the gaps. Recognizing that the scale and the data are decoupled is the whole fix: you keep the continuous scale for positioning but override the tick set to the timestamps you actually have.

Diagnostic checklist

Work the list top to bottom; the first three isolate whether you have a tick-placement problem or a domain-padding problem, and the last two catch the parsing and timezone faults that masquerade as alignment bugs.

Root cause analysis

scaleTime is a continuous linear interpolator. It maps only the minimum and maximum timestamps uniformly across the pixel range and ignores the actual spacing between intermediate points. That is correct for uniform series but misleading when intervals vary by orders of magnitude — a one-second gap and a one-day gap render identically.

There is also a timezone trap that hides until your data crosses a daylight-saving boundary. scaleTime operates in the browser’s local time, so the same dataset produces different tick positions for a user in New York versus one in Berlin, and around a spring-forward or fall-back transition it can inject or drop a phantom hour, nudging ticks off the grid. Unless you specifically want local-clock semantics, use scaleUtc, which interprets the domain in UTC and is therefore deterministic across regions and immune to DST. Parsing must match: build Date objects from epoch milliseconds or parse with utcParse so the values you hand the scale are already in the same frame of reference the scale uses.

Two compounding factors:

  • Calendar-aligned ticks: timeTicks generates midnight/hour/month boundaries that rarely coincide with sparse samples, producing labels that point at empty space.
  • .nice() overreach: rounding the domain to calendar units adds dead space at the edges and worsens tick misalignment on irregular data.

There is a third, deeper issue that filtering does not address: a continuous time scale also misrepresents the gaps. A one-second interval and a one-day interval between adjacent points render with pixel widths proportional to their real duration, so a dense burst of samples collapses into a sliver while a long quiet stretch dominates the axis. That is sometimes correct — for true time-domain analysis you want real durations — but for event logs, trading sessions, or any series where each sample matters equally, it buries the dense regions. When equal visual weight per sample is the goal, the right tool is not a time scale at all but an ordinal or point scale over the sample index, with the timestamp shown only as a label. Decide which semantic you want before configuring ticks: data-aligned ticks on a continuous scale fix label placement but keep proportional spacing; switching to a point scale fixes spacing but discards real duration.

Calendar ticks versus data-aligned ticks Calendar-aligned ticks fall between sparse data points, while filtered ticks land exactly on real timestamps. calendar ticks ticks miss the data points data-aligned ticks ticks align 1:1 with data filter candidate ticks against the set of real timestamps
Filtering generated ticks against the actual timestamp set replaces misaligned calendar ticks with marks that sit exactly on data points.

Broken vs fixed

// ❌ BROKEN: nice() + default calendar ticks on sparse data
import { scaleTime, axisBottom } from 'd3';

const xScale = scaleTime()
  .domain(extent(data, (d) => d.timestamp) as [Date, Date])
  .range([0, chartWidth])
  .nice();                       // adds dead space, snaps to calendar units

const xAxis = axisBottom(xScale); // emits calendar ticks between the actual points
// ✅ FIXED: manual padding, clamp, and data-aligned tick filtering
import { scaleTime, timeTicks, extent, axisBottom } from 'd3';

const dataTimestamps = new Set(data.map((d) => d.timestamp.getTime())); // O(1) lookup

const [minTime, maxTime] = extent(data, (d) => d.timestamp) as [Date, Date];
const paddingMs = (maxTime.getTime() - minTime.getTime()) * 0.05;       // explicit 5% padding

const xScale = scaleTime()
  .domain([new Date(minTime.getTime() - paddingMs), new Date(maxTime.getTime() + paddingMs)])
  .range([0, chartWidth])
  .clamp(true);                  // out-of-bounds values map to the nearest edge

const customTicks = timeTicks(xScale.domain()[0], xScale.domain()[1], 10)
  .filter((t) => dataTimestamps.has(t.getTime()));                      // keep only real points

const xAxis = axisBottom(xScale).tickValues(customTicks);

The fixed version makes three deliberate substitutions. It replaces .nice() with explicit paddingMs so you control exactly how much breathing room the edges get instead of letting D3 snap to a calendar unit that may add days of dead space. It adds .clamp(true) so a brush or zoom that pushes a value past the domain edge renders at the boundary rather than off-screen. And it passes .tickValues(customTicks) — the set of generated candidates intersected with the real timestamp set via an O(1) Set membership test — so every rendered tick sits on an actual data point. The Set is keyed on getTime() rather than the Date object itself because two distinct Date instances representing the same instant are not === equal, but their millisecond values are; comparing objects would never match and the filter would silently drop every tick.

Step-by-step fix

The order matters: build the lookup structure first so tick filtering is O(1) per candidate, set the domain explicitly so you control the padding, then filter ticks and normalize the timezone. Steps four and five are independent of the alignment fix and can be applied on their own if your only symptom is DST drift.

  1. Build a timestamp set. const set = new Set(data.map((d) => d.timestamp.getTime())) for O(1) membership checks.
  2. Compute manual padding. Take extent(), derive paddingMs = (max - min) * 0.05, and offset the domain explicitly instead of .nice().
  3. Enable clamping. Call .clamp(true) so brushing or zoom never renders marks outside the viewport.
  4. Filter candidate ticks. Generate with timeTicks(...) then keep only those whose getTime() is in your set, and pass them to axis.tickValues().
  5. Normalize to UTC. Swap scaleTime for scaleUtc and parse with utcParse to eliminate DST-induced domain shifts.
import { useMemo } from 'react';
import { scaleUtc, extent } from 'd3';

interface Row { timestamp: number; }

// A11Y: callers pair the returned scale with role="img" + an aria summary of the axis.
export function useTimeScale(data: Row[], width: number) {
  return useMemo(() => {
    if (!data.length) return null;
    const [min, max] = extent(data, (d) => new Date(d.timestamp)) as [Date, Date];
    const padding = (max.getTime() - min.getTime()) * 0.05;
    return scaleUtc()
      .domain([new Date(min.getTime() - padding), new Date(max.getTime() + padding)])
      .range([0, width])
      .clamp(true);
    // PERF: recompute only when data or width changes structurally.
  }, [data, width]);
}

Verification

  • Tick alignment: console.assert(customTicks.every((t) => dataTimestamps.has(t.getTime())), 'tick off data').
  • Viewport fit: confirm xScale.range() matches container width and no label’s bounding box exceeds the SVG; clamp(true) should keep everything inside.
  • DST check: render the same data through scaleTime and scaleUtc; if axis output diverges around March/November, the local scale is injecting phantom hours — keep UTC.
  • Parse safety: log parsed Date objects and assert none are Invalid Date before computing the domain. An Invalid Date silently poisons extent(), producing a NaN domain that maps every mark to NaN pixels — guard with Number.isFinite(d.getTime()) at ingestion.
  • Tick count sanity: confirm the filtered tick set is not empty. If timeTicks and your data never coincide (because the requested count is too low to generate any candidate near a real point), the axis renders with no labels at all; in that case raise the candidate count passed to timeTicks or fall back to tickValues(data.map(d => d.timestamp)) directly.

Edge cases & gotchas

  • Frameworks: memoize the scale (useMemo in React, computed in Vue) keyed on data length and bounds so re-renders do not rebuild it and cause jitter.
  • Very large datasets: if tick generation exceeds ~50ms, precompute tick arrays server-side or offload to a Web Worker.
  • Join keys: duplicated or missing timestamps used as join keys create phantom nodes that distort the computed domain — sanitize before binding, per data joins and key functions. A timestamp is a poor join key precisely because two events can share one and because the value is not a stable identity; use a real record id and keep the timestamp as a positioning field only.
  • Zoom and brush: when the chart is zoomable, the visible domain changes on every zoom event, so regenerate the filtered tick set against the rescaled scale rather than the original — otherwise ticks vanish or bunch at one end as the user zooms in. Reuse the same scale instance for both positioning and tick generation so the two stay coupled.