CanvasXpress Number Formats

Introduction to Number Formats

Set numberFormat once and every displayed number follows: axis tick values, hover tooltips, legend labels (including the size-by bins and continuous color ramps) and the data values drawn on the chart. Without it, CanvasXpress keeps its compact scientific defaults (1.2e+6); with it, readers see 1,200,000, 1.2M, $1.2M or 1.200.000 as your audience expects.

A format is a preset name, a sprintf string, or an object. Formatting is powered by the browser's Intl.NumberFormat (with a built-in fallback), so any BCP-47 locale works without shipping locale tables.

Quick Start

One option turns raw magnitudes into compact labels on every surface:

var revenue = {
  "y": {
    "vars": ["Revenue"],
    "smps": ["North", "South", "East", "West"],
    "data": [[1250000, 2400000, 890000, 3100000]]
  }
};
var cXNf1 = new CanvasXpress("canvasNf1", revenue, {
  graphType: "Bar",
  title: "Regional revenue",
  numberFormat: "compact",
  showDataValues: true,
  theme: "CanvasXpress"
});

Presets and sprintf Strings

A string value is either a preset — comma, percent, dollar, euro, pound, yen, compact — or a sprintf format such as "%.1f". Percent follows the Intl convention: the value 0.256 renders as 26%.

numberFormat: "comma"     // 1,234,568
numberFormat: "dollar"    // $1,234,567.89
numberFormat: "compact"   // 1.2M
numberFormat: "%.1f"      // 1234567.9 (sprintf)

The Format Object

The object form gives full control — locale, style, currency, decimals, grouping and free prefix/suffix text:

var cXNf2 = new CanvasXpress("canvasNf2", revenue, {
  graphType: "Bar",
  title: "Umsatz nach Region",
  numberFormat: { locale: "de-DE", style: "currency", currency: "EUR", decimals: 0 },
  showDataValues: true,
  theme: "CanvasXpress"
});

All keys are optional: { locale, style: "decimal" | "percent" | "currency" | "compact", currency, decimals, grouping, prefix, suffix }. For example { prefix: "~", suffix: " kg", grouping: true } renders ~1,234 kg.

Per-Surface Overrides

Each display surface can override the global format: tooltipNumberFormat, legendNumberFormat, dataLabelNumberFormat, and per axis xAxisNumberFormat, yAxisNumberFormat, zAxisNumberFormat and xAxis2NumberFormat. A surface without its own format falls back to numberFormat; with neither set, the legacy output is unchanged.

This is where large size-by legends stop mixing notations: with legendNumberFormat: "compact" a population legend reads 0 - 200M … 1.2B - 1.4B instead of 0 - 2e+8 … 200000000 - 4e+8.

{
  graphType: "Scatter2D",
  sizeBy: "pop",
  legendNumberFormat: "compact",     // legend bins: 200M - 400M
  tooltipNumberFormat: "comma",      // hover: 1,234,568
  yAxisNumberFormat: { style: "percent", decimals: 0 }
}

Axes: Interplay with Tick Formats

The earlier per-axis xAxisTickFormat / yAxisTickFormat (a sprintf string, or [format, transform]) still exists and always wins on its axis when both are set. Axis widths are measured with the formatted strings, so long grouped labels get the room they need.

From R

ggplot2 charts converted with the canvasXpress R package keep their scales' label functions automatically: scale_y_continuous(labels = scales::label_percent()) arrives as the exact tick text ggplot rendered (10%, 20%, …). For hand-written configurations from R or Python, set numberFormat like any other parameter.

From the Menus

Right-click a chart: each axis menu has a Number Format submenu, and General → Number Format sets the global, tooltip, legend and data-label formats. In the Customizer, the Axes panel carries a Number Format field per axis, and every *NumberFormat option is reachable through Customizer search (JSON accepted for the object form).

Scope and Limits

• All formats are off by default; existing charts render byte-identically.
• Non-numeric text (category names, joined value lists) always passes through untouched.
• Formatter instances are memoized per format spec, so large axes and legends pay the Intl construction cost once.
• Data-table columns keep their own dataTableColFormat (sprintf per column).