D3 Value Formatters

See the Value Formatters for more information on getting
started with valueFormatter.

Formatting Numbers with d3-format

Dash AG Grid includes the d3-format library, so you have access to all d3-format
functions to use with valueFormatter.

The basic syntax for the d3 function is: d3.format(specifier)(value)

For example:

d3.format(".0%")(0.123);  # rounded percentage, "12%"
d3.format("($.2f")(-3.5); # localized fixed-point currency, "(£3.50)"
d3.format("+20")(42);     # space-filled and signed, "                 +42"
d3.format(".^20")(42);    # dot-filled and centered, ".........42........."
d3.format(".2s")(42e6);   # SI-prefix with two significant digits, "42M"
d3.format("#x")(48879);   # prefixed lowercase hexadecimal, "0xbeef"
d3.format(",.2r")(4223);  # grouped thousands with two significant digits, "4,200"

For more options, see d3-format examples

If this looks familiar to you, it’s because this JavaScript library is based on Python!

So d3.format(".0%")(0.123) is like "{:.0%}".format(0.123) in Python. The specifiers are based on
the Python’s Format Specification.

In dash-ag-grid, use the d3.format function in the column definitions like this:

# example valueFormatter for currency
columnDefs = [
  {
    "valueFormatter": {"function": "d3.format('($,.2f')(params.value)"},
  },
]

Examples: Number formatting

Here is a simple example of formatting numbers with d3.format function:

Here are examples using the Plolty “Gapminder” dataset with and without number formatting.

Example: d3.format specifiers

Here are examples of formatting numbers with some of the specifiers available in the d3.format function.

Locales

Locales adapt the behavior of d3-format to various languages and places. The definition may include the following
properties:

Note that the thousands property is a misnomer, as the grouping definition allows groups other than thousands.

The default locale for d3.format is U.S. English, which sets:

{
  "decimal": ".",
  "thousands": ",",
  "grouping": [3],
  "currency": ["$", ""]
}

To render currency numbers in French, you could override these default marks by specifying instead a locale such as:

{
  "decimal": ",",
  "thousands": " ",
  "grouping": [3],
  "currency": ["", "€"],
  "nan": "",
}

The decimal separator becomes a comma, thousands are separated by a space, and the default currency mark, the euro
symbol, appears after the number.
This example includes changing the default for not-a-number from NaN to ""

Locales are not loaded by default - you can find them here. Their
definition can be fed to d3.formatLocale:

locale_en_GB = """d3.formatLocale({
  "decimal": ".",
  "thousands": ",",
  "grouping": [3],
  "currency": ["£", ""]
})"""

Then in can be used in the valueFormatter:

columnDefs = [
  {
    "field": "UK",
    "valueFormatter": {"function": f"{locale_en_GB}.format('$,.2f')(params.value)"},
  },
]

Example: Formatting with locale

In this example, each column is formatted with the specifier '$,.2f'. The locale determines how the numbers will be
displayed.
Note that we also set a custom NaN value in the “France” column. Instead of displaying “NaN” it will be blank.

Editable example

In this table try changing the specifier and the values.

Formatting Dates and Times with d3-time-format

Dash AG Grid includes the d3-time-format library, so you have access to
all d3-time-format functions to use with valueFormatter.

The basic syntax for formatting a date object is:

formatted_date_string = d3.timeFormat(specifier)(date object)

d3.timeFormat() is like strftime() in Python.

Note that even if your datetime data is an object on the server, when it’s sent to the grid in the browser it’s
converted to a string.
See Example: Formatting Dates defined as datetime.

If the datetime data uses the ISO string format 'yyyy-mm-dd' it will be automatically inferred into JavaScript date
object the first time that row data is passed into the grid,
using Cell Data Types.
If the datetime data uses another format like 'dd/mm/yyyy', it is possible to:

d3.timeParse() is like strptime() in Python

When the date is converted to a JavaScript date object, then the AG Grid date filter agDateColumnFilter will work out
of the box, and no additional date filter comparator functions are required.

Here are the specifiers:

Example: Formatting Dates defined as strings

Example: Formatting Dates defined as datetime