d3-format module overview
d3-format formats numbers for human consumption. It provides format creation, SI-prefix formatting, format specifier parsing, and locale customization for different number formatting conventions.
d3-format
33 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
d3-format functions overview
d3-format main functions: d3.format (alias for locale.format), d3.formatPrefix (alias for locale.formatPrefix), d3.formatSpecifier (parse format specifier), d3.precisionFixed (compute decimal precision for fixed-point), d3.precisionPrefix (compute decimal precision for SI-prefix), d3.precisionRound (compute significant digits for rounded notation), d3.formatLocale (define custom locale), d3.formatDefaultLocale (define default locale).
d3.format() function signature
d3.format(specifier) returns a new format function for the given string specifier. The returned function takes a number as the only argument and returns a string representing the formatted number. It is an alias for locale.format() on the default locale.
d3.formatPrefix() function signature
d3.formatPrefix(specifier, value) returns a new format function. The returned function converts values to the units of the appropriate SI prefix for the specified numeric reference value before formatting in fixed point notation. It is an alias for locale.formatPrefix() on the default locale.
d3.formatLocale() function signature
d3.formatLocale(definition) returns a locale object for the specified definition with locale.format() and locale.formatPrefix() methods. The definition must include: decimal (string, the decimal point), thousands (string, the group separator), grouping (array of group sizes, cycled as needed), and currency (array of currency prefix and suffix). Optional properties are: numerals (array of ten strings to replace numerals 0-9), percent (string, defaults to '%'), minus (string, defaults to '−'), and nan (string, defaults to 'NaN').
d3.formatDefaultLocale() function signature
d3.formatDefaultLocale(definition) is equivalent to d3.formatLocale(), except it also redefines d3.format() and d3.formatPrefix() to the new locale's locale.format() and locale.formatPrefix(). If not set, the default locale is U.S. English.
d3.format specifier syntax
The general form of a format specifier is [[fill]align][sign][symbol][0][width][,][.precision][~][type]. The fill can be any character. The align character must be one of: > (right-align, default), < (left-align), ^ (center), or = (like >, but with sign and symbol to the left of padding). The sign can be: - (nothing for zero or positive, minus for negative, default), + (plus for zero or positive, minus for negative), ( (nothing for zero or positive, parentheses for negative), or space (space for zero or positive, minus for negative). The symbol can be: $ (apply currency symbols per locale) or # (prefix by 0b, 0o, or 0x for binary, octal, or hexadecimal). The zero (0) option enables zero-padding, implicitly setting fill to 0 and align to =. The width defines the minimum field width. The comma (,) option enables group separator. The precision indicates digits after decimal point (types f and %) or significant digits (types space, e, g, r, s, p). If not specified, precision defaults to 6 except for type space (none), which defaults to 12. The ~ option trims insignificant trailing zeros across all format types.
d3.formatSpecifier with custom precision example
const s = d3.formatSpecifier("f"); s.precision = d3.precisionFixed(0.01); const f = d3.format(s); f(42) returns "42.00" — computing precision based on step and creating a new format.
d3.precisionFixed example
d3.precisionFixed(0.01) returns 2. With step 0.5, d3.precisionFixed(0.5) returns 1, yielding precision for values like 1, 1.5, 2. With step 1, d3.precisionFixed(1) returns 0, yielding precision for values like 1, 2, 3.
d3.format type specifiers
Available format type values are: e (exponent notation), f (fixed point notation), g (decimal or exponent notation, rounded to significant digits), r (decimal notation, rounded to significant digits), s (decimal notation with SI prefix, rounded to significant digits), % (multiply by 100, then decimal notation with percent sign), p (multiply by 100, round to significant digits, then decimal notation with percent sign), b (binary notation, rounded to integer), o (octal notation, rounded to integer), d (decimal notation, rounded to integer), x (hexadecimal notation using lower-case letters, rounded to integer), X (hexadecimal notation using upper-case letters, rounded to integer), c (character data, for a string of text). The type space (none) is shorthand for ~g with default precision of 12 instead of 6. The type n is shorthand for ,g. For types g, n, and space (none), decimal notation is used if the resulting string would have precision or fewer digits; otherwise exponent notation is used.
SI prefix support in formatPrefix
The following SI prefixes are supported in formatPrefix: y (yocto, 10⁻²⁴), z (zepto, 10⁻²¹), a (atto, 10⁻¹⁸), f (femto, 10⁻¹⁵), p (pico, 10⁻¹²), n (nano, 10⁻⁹), µ (micro, 10⁻⁶), m (milli, 10⁻³), space (none, 10⁰), k (kilo, 10³), M (mega, 10⁶), G (giga, 10⁹), T (tera, 10¹²), P (peta, 10¹⁵), E (exa, 10¹⁸), Z (zetta, 10²¹), Y (yotta, 10²⁴).
formatPrefix returns consistent SI prefix
Unlike locale.format() with the s format type, locale.formatPrefix() returns a formatter with a consistent SI prefix rather than computing the prefix dynamically for each number. The precision for the given specifier represents the number of digits past the decimal point (as with f fixed point notation), not the number of significant digits.
d3.formatSpecifier() function signature
d3.formatSpecifier(specifier) parses the specified specifier string, returning an object with exposed fields corresponding to the format specification mini-language and a toString method that reconstructs the specifier. Fields in the returned object are: fill (string), align (string), sign (string), symbol (string), zero (boolean), width (number or undefined), comma (boolean), precision (number or undefined), trim (boolean), and type (string).
new d3.FormatSpecifier() constructor signature
new d3.FormatSpecifier(specifier) takes a specifier object and returns an object with exposed fields corresponding to the format specification mini-language and a toString method that reconstructs the specifier. Fields in the returned object are: fill (string, defaults to ' '), align (string, defaults to '>'), sign (string, defaults to '-'), symbol (string, defaults to ''), zero (boolean, defaults to false), width (number or undefined), comma (boolean, defaults to false), precision (number or undefined), trim (boolean, defaults to false), and type (string, e.g., 's').
d3.precisionFixed() function signature
d3.precisionFixed(step) returns a suggested decimal precision for fixed point notation given the specified numeric step value. The step represents the minimum absolute difference between values that will be formatted, assuming formatted values are also multiples of step.
d3.precisionPrefix() function signature
d3.precisionPrefix(step, value) returns a suggested decimal precision for use with locale.formatPrefix() given the specified numeric step and reference value. The step represents the minimum absolute difference between values to be formatted, and value determines which SI prefix will be used. The precision returned represents the number of digits past the decimal point.
d3.precisionRound() function signature
d3.precisionRound(step, max) returns a suggested decimal precision for format types that round to significant digits given the specified numeric step and max values. The step represents the minimum absolute difference between values to be formatted, and max represents the largest absolute value that will be formatted, assuming formatted values are also multiples of step.
d3.format example with fixed point
const f = d3.format(".2f"); formats numbers with two decimal places in fixed point notation.
d3.format example with percentage
d3.format(".0%")(0.123) returns "12%" — a rounded percentage.
d3.format example with currency
d3.format("($.2f")(-3.5) returns "(£3.50)" — localized fixed-point currency with parentheses for negative values.
d3.format example with space-filled signed
d3.format("+20")(42) returns " +42" — space-filled and signed with plus.
d3.format example with dot-filled centered
d3.format(".^20")(42) returns ".........42........." — dot-filled and centered.
d3.format example with SI prefix
d3.format(".2s")(42e6) returns "42M" — SI-prefix with two significant digits.
d3.format example with hexadecimal
d3.format("#x")(48879) returns "0xbeef" — prefixed lowercase hexadecimal.
d3.format example with grouped thousands and significant digits
d3.format(",.2r")(4223) returns "4,200" — grouped thousands with two significant digits.
d3.formatPrefix example
const f = d3.formatPrefix(",.0", 1e-6); creates a formatter with consistent SI prefix (micro in this case). f(0.00042) returns "420µ" and f(0.0042) returns "4,200µ".
d3.formatSpecifier example
d3.formatSpecifier("s") returns FormatSpecifier { fill: " ", align: ">", sign: "-", symbol: "", zero: false, width: undefined, comma: false, precision: undefined, trim: false, type: "s" }.
d3.precisionFixed example with percent format
const p = Math.max(0, d3.precisionFixed(0.05) - 2); const f = d3.format("." + p + "%"); f(0.45) returns "45%", f(0.50) returns "50%", f(0.55) returns "55%" — for percent format, subtract two from the fixed precision.
d3.precisionPrefix example
d3.precisionPrefix(1e5, 1.3e6) returns 1. const p = d3.precisionPrefix(1e5, 1.3e6); const f = d3.formatPrefix("." + p, 1.3e6); f(1.1e6) returns "1.1M", f(1.2e6) returns "1.2M", f(1.3e6) returns "1.3M" — for values like 1.1e6, 1.2e6, 1.3e6 with step 1e5 and reference 1.3e6.
d3.precisionRound example
d3.precisionRound(0.01, 1.01) returns 3. const p = d3.precisionRound(0.01, 1.01); const f = d3.format("." + p + "r"); f(0.99) returns "0.990", f(1.0) returns "1.00", f(1.01) returns "1.01" — for values 0.99, 1.0, 1.01 with step 0.01 and max 1.01.
d3.precisionRound example with exponent
const p = Math.max(0, d3.precisionRound(0.01, 1.01) - 1); const f = d3.format("." + p + "e"); f(0.01) returns "1.00e-2", f(1.01) returns "1.01e+0" — for exponent format type, subtract one from the round precision.
Trim insignificant zeros with ~ option
The ~ option trims insignificant trailing zeros across all format types. d3.format("s")(1500) returns "1.50000k", but d3.format("~s")(1500) returns "1.5k" — the ~ option removes trailing zeros.
Format type space (none) behavior
d3.format(".2")(42) returns "42", d3.format(".2")(4.2) returns "4.2". d3.format(".1")(42) returns "4e+1", d3.format(".1")(4.2) returns "4" — when type is space (none), decimal notation is used if the result has precision or fewer digits; otherwise exponent notation is used.