Scales and axes

Scale choices belong to the field roles; axis preferences only control how the resulting scale is drawn. An axis setting therefore cannot change what the data means.

Family defaults

Omit scale for the family default:

• column and bar categories use band; values use linear and include zero;
• line categories use band; values use linear without forcing zero;
• area categories use band; values use linear and include zero;
• scatter x and y use linear;
• waterfall steps use a fixed band in row order; values use linear and include zero unless focus is "changes".

Set an explicit scale when the source field carries different intent.

Each chart type accepts only some combinations:

Inferred column, bar, and area value domains include zero.

Dates and time

Use utc when chronological distance matters:

{
  "category": {
    "field": "date",
    "scale": { "type": "utc" },
    "format": "%b %d"
  },
  "categoryAxis": { "format": "%b %d" }
}

Date strings are parsed as UTC rather than local browser time, keeping server images, embeds, and Figma output consistent. Year strings such as "2026" are treated as years; %Y formats annual ticks.

UTC columns and bars take one consistent width from the smallest gap between adjacent dates and leave missing periods as visible gaps. spacing.category and grouped spacing.series still apply. There is no binning or time-unit syntax; aggregate your rows first if you need weekly or monthly bars. A line may also use UTC on its value role when the measure itself is a date or time.

Logarithmic scales

Use log only for positive finite values. It is useful when ratios or orders of magnitude matter more than absolute distance.

{
  "type": "scatter",
  "x": { "field": "parameters", "scale": { "type": "log" } },
  "y": { "field": "compute", "scale": { "type": "log" } }
}

Zero and negative values are invalid on a log role. Column, bar, and area value roles reject log because their bars and areas encode distance from zero; ranged columns and bars accept it because they have no baseline.

Axis preferences

Cartesian families expose categoryAxis and valueAxis; scatter exposes xAxis and yAxis.

{
  "values": {
    "type": "long",
    "field": "revenue",
    "scale": { "type": "linear", "domain": [0, 100], "nice": false }
  },
  "valueAxis": {
    "title": "Revenue ($M)",
    "format": ".0f"
  }
}

Omit the axis preference to use Szum’s defaults. Set it to true to show default settings, or provide an object such as { title: "Revenue" } to show customized settings. Set it to false to hide the axis without removing its scale from layout or semantics. Configuration objects do not need a display property.

Axis titles wrap to two lines within the chart. Longer titles end with an ellipsis in the image while the full text remains in the chart definition.

Axis lines and plot border

Set line on a visible axis to show or hide its line independently of ticks, labels, and grids. Set plotBorder on a Cartesian config to show or hide the full rectangle around the plotting area:

{
  "categoryAxis": { "line": false },
  "valueAxis": { "line": true },
  "plotBorder": false
}

Scatter uses xAxis.line and yAxis.line. Pie has no axis-line or plot-border settings. Omit a setting to follow the theme: Technical draws a full border, Noir and Loud draw no axis lines, and Editorial, Clean, and Soft draw only the category axis line.

A visible plot border includes all four edges even when an axis or its line is hidden. Hiding the border leaves independently visible axis lines in place. Overlapping edges draw once. Both use the theme’s axis stroke color and width, customizable through themeOverrides.colors.axes.line and themeOverrides.axes.lineWidth.

Axis-line and plot-border visibility are available on every plan. Custom stroke colors and widths are theme overrides, which need a paid plan.

Explicit domains

Continuous domains use a two-number extent. Band domains use an array of category values. An explicit domain is appropriate when charts must share a comparison frame or when domain order is part of the story.

A continuous domain crops the chart without removing data. Lines and areas keep their true crossings; bars and intervals are cut at the window edge. Cropping does not recalculate stacks, percentages or statistics. Labels attached outside the window are omitted. Tooltips retain original values for visible observations and partially visible bars; crossings do not create interpolated observations.

Do not use a clipped domain to exaggerate column, bar, or area differences. Szum keeps an explicit compatible domain exactly but emits the non-blocking axis_zero_baseline_excluded warning when a column, bar, or area value domain excludes zero. MCP actions require approval of that exact warning; HTTP renders proceed and report it in the X-Chart-Diagnostics header. Line and scatter may use non-zero domains when doing so is analytically honest.

Visible references contribute to automatic continuous domains by default, so a benchmark remains visible after filtering reduces the data extent. Set contributeToDomain: false on a reference to keep the automatic domain data-driven. Explicit domains and normalized-share bounds always win; an out-of-range reference is omitted without an automatic footnote. Reference statistics are calculated before domain contribution, and references never become observations. Text annotations do not expand automatic domains.

Tick formatting

Numeric ticks and values use D3 format syntax, written with the chart locale’s separators: ",.0f" prints 1,234 in en-US and 1.234 in de-DE. Common forms include:

• ",.0f" – grouped whole numbers;
• ".1f" – one decimal place;
• ".2~s" – compact notation with K, M, B, and T, such as "8.1B"; values below 1 stay plain decimals;
• ".0%" – a fraction displayed as a percentage.

UTC axes use D3 time-format syntax, such as %Y, %b, or %b %d.

Role format controls values in labels, tooltips, and accessible descriptions. Without one, UTC values read at their data’s precision in the chart locale, such as Jan 2025 or Jan 5, 2025, 09:00. Axis format controls only that axis’s ticks. Set both when both should look the same; otherwise Szum picks an automatic format for each.

Automatic value formatting keeps small nonzero values visible and uses scientific notation for extreme magnitudes. In English locales, a measure that reaches 10,000 reads compactly on its labels and value axis, such as 416B, with one shared precision per unit. An explicit role format always takes precedence.

Money

Set currency on long or wide values, pie values, or waterfall values when the measure is money. It takes an ISO 4217 code:

{
  "values": { "type": "long", "field": "net_income", "currency": "USD" }
}

Labels, tooltips, references, and the value axis then write the currency in the chart locale, such as $416B, −$221B, or $1,443. Whole amounts carry no cents unless the values include fractions. Percentages stay plain. currency replaces format for money, so a value role cannot set both.

Automatic behavior

Szum validates field compatibility, derives the observed domain, applies the chart type’s baseline rule, and includes compiled stack extents and eligible reference values. It may expand automatic continuous domains to readable bounds; explicit domains retain their authored bounds. Tick density adapts to the available space without deleting source rows or changing the scale.