Number formats in Dart

Control how a value is displayed without changing the value itself.

Install#

dart pub add excel_plus

import 'package:excel_plus/excel_plus.dart';

Currency and percentages#

// Currency with a thousands separator, using a custom format code.
sheet.updateCell(
  CellIndex.indexByString('A1'),
  DoubleCellValue(12500.5),
  cellStyle: CellStyle(numberFormat: NumFormat.custom(formatCode: r'$#,##0.00')),
);

// Percentage, using a built in format.
sheet.updateCell(
  CellIndex.indexByString('A2'),
  DoubleCellValue(0.125),
  cellStyle: CellStyle(numberFormat: NumFormat.standard_10),
);

Note the raw value for a percentage is the fraction, so 0.125 displays as 12.50%. Storing 12.5 instead would display as 1250.00%.

Dates#

Write a real date value and let the number format decide how it looks. That keeps sorting and filtering working in Excel.

sheet.updateCell(
  CellIndex.indexByString('A1'),
  DateCellValue(year: 2026, month: 6, day: 9),
  cellStyle: CellStyle(numberFormat: NumFormat.custom(formatCode: 'dd/mm/yyyy')),
);

Common format codes#

Custom codes#

Any format code Excel understands can be passed through. Use a raw string in Dart so a leading currency symbol is not read as string interpolation.

NumFormat.custom(formatCode: r'$#,##0.00');
NumFormat.custom(formatCode: '0.0"kg"');
NumFormat.custom(formatCode: r'[>=1000]#,##0,"k";0');

Showing a cell the way Excel would#

Reading a cell gives you the stored value, not the text a spreadsheet displays. 1234.5 under an accounting format is still 1234.5 in Dart. To render a sheet into your own table, grid or PDF you need the formatted string, and that renderer is public.

// The whole cell, using its own number format.
final cell = sheet.cell(CellIndex.indexByString('B2'));
print(cell.displayText); // 1,234.50

// Or a value against any format you choose.
NumFormat.standard_4.format(1234.5);   // 1,234.50
NumFormat.standard_9.format(0.25);     // 25%
NumFormat.custom(formatCode: 'yyyy-mm-dd')
    .format(DateTime.utc(2026, 3, 4)); // 2026-03-04

This is the same renderer the TEXT function uses, so the two always agree. Text is returned unchanged, an empty cell gives an empty string, and a formula cell shows its cached result when the file carried one.

Built-in format ids#

Excel reserves a set of numbered formats a file can reference without spelling out a code. The currency ids (5 to 8) and the accounting ids (41 to 44) are the ones most real files use, and they read and write as themselves rather than falling back:

Ids 23 to 36 are left unmapped on purpose. The spec reserves them and their meaning depends on the locale, so there is no single code that is correct to write back. A file using one still opens: the id is preserved and the cell falls back rather than being rewritten as something else.