Chart Scales & Axes

Szum infers scale types from your data. Most charts need zero axis configuration.

Auto-inference

Data values	Inferred scale	Example
Numbers	`linear`	`42`, `3.14`
ISO date strings	`utc`	`"2026-03-15"`
Other strings	`band` (categorical)	`"Jan"`, `"Organic"`

For annual trends where spacing represents time, use four-digit strings and an explicit UTC axis so Szum can distinguish time from categories or measurements. Do not invent a January 1 or December 31 date when the source only identifies a year:

{
  "x": { "type": "utc", "tickFormat": "%Y" },
  "data": [{ "year": "2024", "value": 42 }],
  "marks": [{ "type": "line", "x": "year", "y": "value" }]
}

Numeric values on UTC axes are Unix milliseconds, so convert numeric source years to strings. Without an explicit UTC axis, numeric years remain linear and year strings remain categorical. Keep that categorical representation only when years are intentionally discrete labels rather than a time axis.

Axis config

Both x and y accept the same fields:

Field	Type	Default	Description
`type`	"linear" \| "log" \| "utc" \| "band"	`auto`	Override the inferred scale type.
`domain`	[min, max] or string[]	`auto`	Force a specific range.
`nice`	boolean	`auto`	Extend an inferred continuous domain to round values.
`label`	string	`–`	Axis label text.
`tickFormat`	string	`–`	D3 format specifier for tick labels.
`display`	boolean	`true`	Set false to hide the axis.

Custom domain

Set a specific range for the y-axis:

Tick formatting

Use D3 format specifiers to control how tick labels display. Click a format to see it applied:

$,.0f→$1,200

Logarithmic scales

Set type: "log" when equal ratios should take equal space. Log scales are base 10 and explicit-only—they are never inferred from numeric data. Every value and explicit domain endpoint on the axis must be a finite number greater than zero.

Log axes label powers of ten by default. When fewer than two powers of ten fall within the domain, Szum retains intermediate labels.

Log scales are unavailable on the zero-baseline value axes used by bar and area marks. Use line, dot, text, or rule marks for logarithmic comparisons.

UTC dates

ISO date strings are auto-detected. Tick labels format by granularity:

Daily data → Mar 15
Monthly data → Mar
Yearly data → 2025

Dates are parsed as UTC. Use ISO dates (YYYY-MM-DD) or full ISO datetimes when the source identifies a real month, day, or instant.

UTC also works as the category axis of barY or barX. Szum derives each bar's interval from the closest adjacent timestamps, so missing periods remain visible as gaps and grouped bars can use group: "dodge".

Automatic behaviors

Zero baseline: Bar and area marks include zero on their value axis when the domain is inferred. If you set an explicit domain, Szum preserves it exactly and bounds the rendered mark to the visible range. Use a line or dot chart – not a bar or filled area – when a non-zero domain is needed to emphasize change.

Continuous domains: Data-derived linear and log domains extend to round tick values by default. Inferred UTC domains stop at the observed endpoints; set nice: true to extend them to round calendar boundaries. Temporal bar category axes span the complete inferred bar intervals by default, so the first and last bars are not clipped. Explicit domains are always preserved exactly.

Tick labels: Overlapping x-axis labels stay horizontal when possible. Category labels wrap to two lines at word boundaries; labels without useful breaks rotate -90° when the chart has enough height. If neither treatment can preserve the plot area, labels truncate with an ellipsis.

Tick count: Computed from available space – roughly one tick per 90px on x for date scales, one per 50px for other scales, and one per 2.5× font size on y. For date scales, the count is also capped at the number of data points to avoid synthetic intermediate ticks.

Scales and axes