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#

Format code	Shows
`0`	Whole number
`0.00`	Two decimal places
`#,##0`	Thousands separator
`0.00%`	Percentage
`dd/mm/yyyy`	Date
`hh:mm:ss`	Time
`#,##0.00;[Red]-#,##0.00`	Negatives in red

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');