Numeral Column Type

The optional @revolist/revogrid-column-numeral package supplies a numeric text editor, a number renderer, and right-aligned cells. It works with Core and does not require Pro. Use it for existing Numeral.js masks or its abbreviation, ordinal, byte, and seconds-duration formats. For per-column country and currency settings, use Number formats.

1. Register a reusable column type

pnpm add @revolist/revogrid-column-numeral

With an initialized RevoGrid instance:

import NumberColumnType from '@revolist/revogrid-column-numeral';

grid.columnTypes = { amount: new NumberColumnType('0,0.00') };
grid.columns = [{ prop: 'amount', name: 'Amount', columnType: 'amount' }];
grid.source = [{ amount: 1234.56 }]; // Displays 1,234.56 in the default locale.

Omit the constructor argument for the default mask 0,0[.]00. The editor uses a text input and commits parsed numbers; it does not provide min, max, or step constraints. Add application validation when these are required.

2. Choose a format

Replace the constructor mask above with any mask below. Outputs assume the default English locale and the default percentage scaling. Display rounding does not round the stored value.

Family	Stored number	Mask	Display	Typical use
Integer and grouping	1234.56	0,0	1,235	Counts
Fixed decimals	1234.56	0,0.00	1,234.56	Amounts
Optional decimals	12.5	0.0[00]	12.5	Measurements
Optional decimal separator	12	0[.]00	12	Whole or decimal values
Leading zero padding	12	00000	00012	Numeric display codes
Omit leading zero	0.25	.00	.25	Compact ratios
Explicit sign	12.5	+0.00	+12.50	Changes and deltas
Negative parentheses	-12.5	(0.00)	(12.50)	Financial reports
Currency symbol	1234.56	$0,0.00	$1,234.56	Single-currency amounts
Currency suffix	1234.56	0,0.00 $	1,234.56 $	Alternate symbol placement
Automatic abbreviation	1230974	0.0a	1.2m	BI cards and summaries
Forced abbreviation	1230974	0.0ak	1231.0k	Consistent thousands scale
Percentage	0.125	0.0%	12.5%	Rates
Basis points	0.0012	0 BPS	12 BPS	Yield and spread changes
Exponential	123456	0.00e+0	1.23e+5	Scientific values
Decimal bytes	2000	0.0 b	2.0 KB	Storage in powers of 1000
Binary bytes	2048	0.0 ib	2.0 KiB	Memory in powers of 1024
Ordinal	2	0o	2nd	Ranking labels
Elapsed seconds	3661	00:00:00	1:01:01	Duration counters

Abbreviation suffixes can be forced with ak, am, ab, or at. A space before a, b, ib, or % controls label spacing. These are Numeral.js masks; Excel format codes and Intl.NumberFormat options use different syntax.

Use nonnegative whole seconds for the time mask; fractional seconds can round to 60 without carrying into the minutes. It supports hours beyond 24; it does not handle calendar dates or time zones. Spreadsheet elapsed-time codes use day fractions. Use the separate duration and time articles before exchanging these values.

3. Configure the shared Numeral instance

Call the static method to access the same instance used by this editor:

const numeral = NumberColumnType.getNumeralInstance();
numeral.register('locale', 'app-euro', {
  delimiters: { thousands: '.', decimal: ',' },
  abbreviations: { thousand: 'k', million: 'm', billion: 'b', trillion: 't' },
  ordinal: () => '.',
  currency: { symbol: '€' },
});
numeral.locale('app-euro');
grid.columnTypes = { amount: new NumberColumnType('0,0.00 $') };
// 1234.56 displays as 1.234,56 €.

Register a locale once during application startup. Locale selection is global to this Numeral instance and affects all numeral columns and their input parsing. It is not a per-column option, does not automatically load browser locales, and does not implement country-specific grouping such as Indian lakh grouping. The $ token uses the active locale’s symbol; it is not an ISO currency selector. For mixed countries or currencies in one grid, use Pro value presets or an explicit Intl.NumberFormat cell template.

The shared instance also exposes localeData(), register('format', name, definition), zeroFormat(), nullFormat(), defaultFormat(), and options such as scalePercentBy100. These settings affect other consumers of that instance. The column always supplies its constructor mask, so defaultFormat() does not replace that mask. A null source value bypasses Numeral formatting and displays blank, so nullFormat() does not provide a null-cell placeholder.

For a display-only transformation, the optional second constructor argument receives the event name beforeValueFormatted and a mutable Numeral object:

const thousands = new NumberColumnType('0,0.0', (_event, value) => {
  value.divide(1000);
});

This callback changes display only. Label the column with its scale, and define input conversion separately if users should enter thousands. The constructor does not expose Numeral’s optional rounding-function argument.

4. Keep storage and parsing predictable

Store finite numbers in the source. The renderer first calls parseFloat on the raw value; localized strings such as "1.234,56" are therefore unsafe as source values. Null, undefined, empty strings, and unparseable values display blank. A numeric prefix such as "12abc" can display as 12.

The editor parses with numeral(input).value() under the active locale. It can interpret grouping, currency, percent, byte, basis-point, exponential, and seconds-duration input, but parsing is permissive: it is not validation. A blank edit stays an empty string; an unparseable edit stays the original string. Validate before saving, including paste and API updates. The column does not automatically normalize those other write paths.

Use strings for identifiers that must preserve leading zeros or integers beyond JavaScript’s safe integer range. Use decimal arithmetic or integer minor units for exact financial calculations; formatting only controls presentation.

For Excel export, set an explicit Excel-compatible excelExport format through the numeral export helper. Numeral masks such as a, BPS, and ib are not Excel number-format codes.

Package reference: RevoGrid numeral column. Format implementation: Numeral.js 2.0.6.