Number Formatting

ReoGrid Web supports Excel-compatible number format codes. A format code controls how a cell’s raw value is displayed without changing the stored value.

Applying a format

Use setFormat() on a cell or range, or assign to the format property directly.

// Single cell
worksheet.cell('B2').setValue('4999').setFormat('$#,##0.00')

// Range
worksheet.range('B2:B10').setFormat(NumberFormat.currency('$', 2))

// Property assignment
worksheet.cell('C3').format = '0.00%'

// Clear format
worksheet.cell('B2').format = undefined

NumberFormat helpers

The NumberFormat utility generates format codes for common cases. Import it alongside createReogrid:

import { createReogrid, NumberFormat } from '@reogrid/lite'

NumberFormat.number(decimals?, grouping?)

NumberFormat.number()          // '#,##0'       → 1,234,567
NumberFormat.number(2)         // '#,##0.00'    → 1,234,567.89
NumberFormat.number(2, false)  // '0.00'        → 1234567.89

NumberFormat.percent(decimals?)

NumberFormat.percent()   // '0%'     → 43%
NumberFormat.percent(2)  // '0.00%'  → 42.75%

The raw cell value should be a decimal fraction (e.g. '0.4275' displays as 42.75%).

NumberFormat.currency(symbol, decimals?, position?)

NumberFormat.currency('$', 2)            // '$#,##0.00'  → $4,999.00
NumberFormat.currency('€', 2)            // '€#,##0.00'  → €4,999.00
NumberFormat.currency('¥', 0)            // '¥#,##0'     → ¥4,999
NumberFormat.currency('円', 0, 'suffix') // '#,##0円'    → 4,999円

NumberFormat.date(pattern?)

NumberFormat.date()               // 'yyyy-mm-dd'   → 2025-03-17
NumberFormat.date('MM/dd/yyyy')   // 'MM/dd/yyyy'   → 03/17/2025
NumberFormat.date('d MMM yyyy')   // 'd MMM yyyy'   → 17 Mar 2025

The raw value must be an Excel serial date (serial value 1 = 1900-01-01). When loading xlsx files, date cells already carry serial values and format codes — no extra work needed.

NumberFormat.time(pattern?)

NumberFormat.time()               // 'HH:mm:ss'     → 18:00:00
NumberFormat.time('h:mm AM/PM')   // 'h:mm AM/PM'   → 6:00 PM

The raw value must be a decimal fraction of a day (e.g. '0.75' = 18:00).

Using raw format codes

You can also pass any Excel-compatible format code string directly:

worksheet.cell('A1').setFormat('#,##0.0')       // one decimal, grouped
worksheet.cell('A2').setFormat('0.000%')         // percent, 3 decimals
worksheet.cell('A3').setFormat('"€"#,##0.00')   // quoted symbol
worksheet.cell('A4').setFormat('[Red]0.00')      // color modifier

Format codes reference

Thousands scaling

A comma at the end of a format code divides the displayed value by 1,000 — once per comma. It is the standard way to write a summary column in units of thousands or millions.

ws.cell('B2').setFormat('#,##0,')          // 8,500,000  → 8,500
ws.cell('B3').setFormat('#,##0.0,,"M"')    // 2,400,000  → 2.4M

A comma between digit placeholders (#,##0) is a grouping separator and never scales.

Fixed in v1.6.0. A comma placed after the decimal part — 0.0, or #,##0.0,,, which is the arrangement Excel itself writes — did not scale, and the comma was not stripped from the format either, so parsing failed outright: 0.0,,"M" displayed 2,400,000 as 2400000.0,,M. Both forms now work, so a conditional summary format like [>=1000000]#,##0.0,,"M";[>=1000]#,##0.0,"K";0 matches Excel.

Note that the scaled number is rounded to the digits the pattern asks for, so #,##0, on 8,500 reads 9 — reach for it in summary columns, not where the exact figure matters.