Numbro

This tutorial shows you how to create a custom numeric cell type using the Numbro library for locale-aware number formatting.

1
import { HotTable, HotColumn } from '@handsontable/react-wrapper';
2
import { registerAllModules } from 'handsontable/registry';
3
import { rendererFactory, getRenderer } from 'handsontable/renderers';
4
import { getEditor } from 'handsontable/editors';
5
import { getValidator } from 'handsontable/validators';
6
import { registerCellType } from 'handsontable/cellTypes';
7
import numbro from 'numbro';
8
import languages from 'numbro/dist/languages.min.js';
9

10
registerAllModules();
11
Object.values(languages).forEach((language) => numbro.registerLanguage(language));
12

13
function isNumeric(value) {
14
  const type = typeof value;
15

16
  if (type === 'number') {
17
    return !isNaN(value) && isFinite(value);
18
  } else if (type === 'string') {
19
    if (value.length === 0) {
20
      return false;
21
    } else if (value.length === 1) {
22
      return /\d/.test(value);
23
    }
24

25
    const delimiter = Array.from(new Set(['.']))
26
      .map((d) => `\\${d}`)
27
      .join('|');
28

29
    return new RegExp(`^[+-]?(((${delimiter})?\\d+((${delimiter})\\d+)?(e[+-]?\\d+)?)|(0x[a-f\\d]+))$`, 'i').test(
30
      value.trim()
31
    );
32
  } else if (type === 'object') {
33
    return !!value && typeof value.valueOf() === 'number' && !(value instanceof Date);
34
  }
35

36
  return false;
37
}
38

39
const cellTypeDefinition = {
40
  renderer: rendererFactory(({ hotInstance, td, row, col, prop, value, cellProperties }) => {
41
    if (isNumeric(value)) {
42
      let classArr = [];
43

44
      if (Array.isArray(cellProperties.className)) {
45
        classArr = cellProperties.className;
46
      } else {
47
        const className = cellProperties.className ?? '';
48

49
        if (className.length) {
50
          classArr = className.split(' ');
51
        }
52
      }
53

54
      const numericFormat = cellProperties.numericFormat;
55
      const cellCulture = (numericFormat && numericFormat.culture) || 'en-US';
56
      const cellFormatPattern = numericFormat && numericFormat.pattern;
57

58
      if (cellCulture && !numbro.languages()[cellCulture]) {
59
        const shortTag = cellCulture.replace('-', '');
60
        const langData = numbro.allLanguages ? numbro.allLanguages[cellCulture] : numbro[shortTag];
61

62
        if (langData) {
63
          numbro.registerLanguage(langData);
64
        }
65
      }
66

67
      numbro.setLanguage(cellCulture);
68
      value = numbro(value).format(cellFormatPattern ?? '0');
69

70
      if (
71
        classArr.indexOf('htLeft') < 0 &&
72
        classArr.indexOf('htCenter') < 0 &&
73
        classArr.indexOf('htRight') < 0 &&
74
        classArr.indexOf('htJustify') < 0
75
      ) {
76
        classArr.push('htRight');
77
      }
78

79
      if (classArr.indexOf('htNumeric') < 0) {
80
        classArr.push('htNumeric');
81
      }
82

83
      cellProperties.className = classArr.join(' ');
84
      td.dir = 'ltr';
85
    }
86

87
    getRenderer('text')(hotInstance, td, row, col, prop, value, cellProperties);
88
  }),
89
  validator: getValidator('numeric'),
90
  editor: getEditor('numeric'),
91
};
92

93
registerCellType('numbro', cellTypeDefinition);
94

95
/* start:skip-in-preview */
96
const data = [
97
  {
98
    id: 640329,
99
    itemName: 'Lunar Core',
100
    itemNo: 'XJ-12',
101
    leadEngineer: 'Ellen Ripley',
102
    cost: 350000,
103
    inStock: true,
104
    category: 'Lander',
105
    itemQuality: 87,
106
    origin: '🇺🇸 USA',
107
    quantity: 2,
108
    valueStock: 700000,
109
    repairable: false,
110
    supplierName: 'TechNova',
111
    restockDate: '2025-08-01',
112
    operationalStatus: 'Awaiting Parts',
113
  },
114
  {
115
    id: 863104,
116
    itemName: 'Zero Thrusters',
117
    itemNo: 'QL-54',
118
    leadEngineer: 'Sam Bell',
119
    cost: 450000,
120
    inStock: false,
121
    category: 'Propulsion',
122
    itemQuality: 0,
123
    origin: '🇩🇪 Germany',
124
    quantity: 0,
125
    valueStock: 0,
126
    repairable: true,
127
    supplierName: 'PropelMax',
128
    restockDate: '2025-09-15',
129
    operationalStatus: 'In Maintenance',
130
  },
131
  {
132
    id: 395603,
133
    itemName: 'EVA Suits',
134
    itemNo: 'PM-67',
135
    leadEngineer: 'Alex Rogan',
136
    cost: 150000,
137
    inStock: true,
138
    category: 'Equipment',
139
    itemQuality: 79,
140
    origin: '🇮🇹 Italy',
141
    quantity: 50,
142
    valueStock: 7500000,
143
    repairable: true,
144
    supplierName: 'SuitCraft',
145
    restockDate: '2025-10-05',
146
    operationalStatus: 'Ready for Testing',
147
  },
148
  {
149
    id: 679083,
150
    itemName: 'Solar Panels',
151
    itemNo: 'BW-09',
152
    leadEngineer: 'Dave Bowman',
153
    cost: 75000,
154
    inStock: true,
155
    category: 'Energy',
156
    itemQuality: 95,
157
    origin: '🇺🇸 USA',
158
    quantity: 10,
159
    valueStock: 750000,
160
    repairable: false,
161
    supplierName: 'SolarStream',
162
    restockDate: '2025-11-10',
163
    operationalStatus: 'Operational',
164
  },
165
  {
166
    id: 912663,
167
    itemName: 'Comm Array',
168
    itemNo: 'ZR-56',
169
    leadEngineer: 'Louise Banks',
170
    cost: 125000,
171
    inStock: false,
172
    category: 'Communication',
173
    itemQuality: 0,
174
    origin: '🇯🇵 Japan',
175
    quantity: 0,
176
    valueStock: 0,
177
    repairable: true,
178
    supplierName: 'CommTech',
179
    restockDate: '2025-12-20',
180
    operationalStatus: 'Decommissioned',
181
  },
182
  {
183
    id: 315806,
184
    itemName: 'Habitat Dome',
185
    itemNo: 'UJ-23',
186
    leadEngineer: 'Dr. Ryan Stone',
187
    cost: 1000000,
188
    inStock: true,
189
    category: 'Shelter',
190
    itemQuality: 93,
191
    origin: '🇨🇦 Canada',
192
    quantity: 3,
193
    valueStock: 3000000,
194
    repairable: false,
195
    supplierName: 'DomeInnovate',
196
    restockDate: '2026-01-25',
197
    operationalStatus: 'Operational',
198
  },
199
];
200
/* end:skip-in-preview */
201

202
const ExampleComponent = () => {
203
  return (
204
    <HotTable
205
      data={data}
206
      colHeaders={['Item Name', 'Category', 'Lead Engineer', 'Quantity', 'Cost']}
207
      autoRowSize={true}
208
      rowHeaders={true}
209
      height="auto"
210
      width="100%"
211
      autoWrapRow={true}
212
      headerClassName="htLeft"
213
      licenseKey="non-commercial-and-evaluation"
214
    >
215
      <HotColumn data="itemName" type="text" width={130} />
216
      <HotColumn data="category" type="text" width={120} />
217
      <HotColumn data="leadEngineer" type="text" width={150} />
218
      <HotColumn
219
        data="quantity"
220
        type="numbro"
221
        width={150}
222
        className="htRight"
223
        numericFormat={{ pattern: '0,0', culture: 'en-US' }}
224
      />
225
      <HotColumn
226
        data="cost"
227
        type="numbro"
228
        width={120}
229
        className="htRight"
230
        numericFormat={{ pattern: '$0,0.00', culture: 'en-US' }}
231
      />
232
    </HotTable>
233
  );
234
};
235

236
export default ExampleComponent;

1
import { HotTable, HotColumn } from '@handsontable/react-wrapper';
2
import { registerAllModules } from 'handsontable/registry';
3
import { rendererFactory, getRenderer } from 'handsontable/renderers';
4
import { getEditor } from 'handsontable/editors';
5
import { getValidator } from 'handsontable/validators';
6
import { registerCellType } from 'handsontable/cellTypes';
7
import numbro from 'numbro';
8
// numbro ships no type declarations for its bundled language pack.
9
// @ts-expect-error -- untyped module
10
import languages from 'numbro/dist/languages.min.js';
11

12
registerAllModules();
13
Object.values(languages).forEach((language) => numbro.registerLanguage(language as numbro.NumbroLanguage));
14

15
function isNumeric(value: unknown): boolean {
16
  const type = typeof value;
17

18
  if (type === 'number') {
19
    return !isNaN(value as number) && isFinite(value as number);
20
  } else if (type === 'string') {
21
    const str = value as string;
22

23
    if (str.length === 0) {
24
      return false;
25
    } else if (str.length === 1) {
26
      return /\d/.test(str);
27
    }
28

29
    const delimiter = Array.from(new Set(['.']))
30
      .map((d) => `\\${d}`)
31
      .join('|');
32

33
    return new RegExp(`^[+-]?(((${delimiter})?\\d+((${delimiter})\\d+)?(e[+-]?\\d+)?)|(0x[a-f\\d]+))$`, 'i').test(
34
      str.trim()
35
    );
36
  } else if (type === 'object') {
37
    return !!value && typeof (value as object).valueOf() === 'number' && !(value instanceof Date);
38
  }
39

40
  return false;
41
}
42

43
const cellTypeDefinition = {
44
  renderer: rendererFactory(({ hotInstance, td, row, col, prop, value, cellProperties }) => {
45
    if (isNumeric(value)) {
46
      let classArr: string[] = [];
47

48
      if (Array.isArray(cellProperties.className)) {
49
        classArr = cellProperties.className as string[];
50
      } else {
51
        const className = (cellProperties.className as string) ?? '';
52

53
        if (className.length) {
54
          classArr = className.split(' ');
55
        }
56
      }
57

58
      const numericFormat = cellProperties.numericFormat as { culture?: string; pattern?: string } | undefined;
59
      const cellCulture = (numericFormat && numericFormat.culture) || 'en-US';
60
      const cellFormatPattern = numericFormat && numericFormat.pattern;
61

62
      if (cellCulture && !numbro.languages()[cellCulture]) {
63
        const shortTag = cellCulture.replace('-', '');
64
        const langData = (numbro as any).allLanguages ? (numbro as any).allLanguages[cellCulture] : (numbro as any)[shortTag];
65

66
        if (langData) {
67
          numbro.registerLanguage(langData);
68
        }
69
      }
70

71
      numbro.setLanguage(cellCulture);
72
      value = numbro(value as number).format(cellFormatPattern ?? '0');
73

74
      if (
75
        classArr.indexOf('htLeft') < 0 &&
76
        classArr.indexOf('htCenter') < 0 &&
77
        classArr.indexOf('htRight') < 0 &&
78
        classArr.indexOf('htJustify') < 0
79
      ) {
80
        classArr.push('htRight');
81
      }
82

83
      if (classArr.indexOf('htNumeric') < 0) {
84
        classArr.push('htNumeric');
85
      }
86

87
      cellProperties.className = classArr.join(' ');
88
      td.dir = 'ltr';
89
    }
90

91
    getRenderer('text')(hotInstance, td, row, col, prop, value, cellProperties);
92
  }),
93
  validator: getValidator('numeric'),
94
  editor: getEditor('numeric'),
95
};
96

97
registerCellType('numbro', cellTypeDefinition);
98

99
/* start:skip-in-preview */
100
interface InventoryItem {
101
  id: number;
102
  itemName: string;
103
  itemNo: string;
104
  leadEngineer: string;
105
  cost: number;
106
  inStock: boolean;
107
  category: string;
108
  itemQuality: number;
109
  origin: string;
110
  quantity: number;
111
  valueStock: number;
112
  repairable: boolean;
113
  supplierName: string;
114
  restockDate: string;
115
  operationalStatus: string;
116
}
117

118
const data: InventoryItem[] = [
119
  {
120
    id: 640329,
121
    itemName: 'Lunar Core',
122
    itemNo: 'XJ-12',
123
    leadEngineer: 'Ellen Ripley',
124
    cost: 350000,
125
    inStock: true,
126
    category: 'Lander',
127
    itemQuality: 87,
128
    origin: '🇺🇸 USA',
129
    quantity: 2,
130
    valueStock: 700000,
131
    repairable: false,
132
    supplierName: 'TechNova',
133
    restockDate: '2025-08-01',
134
    operationalStatus: 'Awaiting Parts',
135
  },
136
  {
137
    id: 863104,
138
    itemName: 'Zero Thrusters',
139
    itemNo: 'QL-54',
140
    leadEngineer: 'Sam Bell',
141
    cost: 450000,
142
    inStock: false,
143
    category: 'Propulsion',
144
    itemQuality: 0,
145
    origin: '🇩🇪 Germany',
146
    quantity: 0,
147
    valueStock: 0,
148
    repairable: true,
149
    supplierName: 'PropelMax',
150
    restockDate: '2025-09-15',
151
    operationalStatus: 'In Maintenance',
152
  },
153
  {
154
    id: 395603,
155
    itemName: 'EVA Suits',
156
    itemNo: 'PM-67',
157
    leadEngineer: 'Alex Rogan',
158
    cost: 150000,
159
    inStock: true,
160
    category: 'Equipment',
161
    itemQuality: 79,
162
    origin: '🇮🇹 Italy',
163
    quantity: 50,
164
    valueStock: 7500000,
165
    repairable: true,
166
    supplierName: 'SuitCraft',
167
    restockDate: '2025-10-05',
168
    operationalStatus: 'Ready for Testing',
169
  },
170
  {
171
    id: 679083,
172
    itemName: 'Solar Panels',
173
    itemNo: 'BW-09',
174
    leadEngineer: 'Dave Bowman',
175
    cost: 75000,
176
    inStock: true,
177
    category: 'Energy',
178
    itemQuality: 95,
179
    origin: '🇺🇸 USA',
180
    quantity: 10,
181
    valueStock: 750000,
182
    repairable: false,
183
    supplierName: 'SolarStream',
184
    restockDate: '2025-11-10',
185
    operationalStatus: 'Operational',
186
  },
187
  {
188
    id: 912663,
189
    itemName: 'Comm Array',
190
    itemNo: 'ZR-56',
191
    leadEngineer: 'Louise Banks',
192
    cost: 125000,
193
    inStock: false,
194
    category: 'Communication',
195
    itemQuality: 0,
196
    origin: '🇯🇵 Japan',
197
    quantity: 0,
198
    valueStock: 0,
199
    repairable: true,
200
    supplierName: 'CommTech',
201
    restockDate: '2025-12-20',
202
    operationalStatus: 'Decommissioned',
203
  },
204
  {
205
    id: 315806,
206
    itemName: 'Habitat Dome',
207
    itemNo: 'UJ-23',
208
    leadEngineer: 'Dr. Ryan Stone',
209
    cost: 1000000,
210
    inStock: true,
211
    category: 'Shelter',
212
    itemQuality: 93,
213
    origin: '🇨🇦 Canada',
214
    quantity: 3,
215
    valueStock: 3000000,
216
    repairable: false,
217
    supplierName: 'DomeInnovate',
218
    restockDate: '2026-01-25',
219
    operationalStatus: 'Operational',
220
  },
221
];
222
/* end:skip-in-preview */
223

224
const ExampleComponent = () => {
225
  return (
226
    <HotTable
227
      data={data}
228
      colHeaders={['Item Name', 'Category', 'Lead Engineer', 'Quantity', 'Cost']}
229
      autoRowSize={true}
230
      rowHeaders={true}
231
      height="auto"
232
      width="100%"
233
      autoWrapRow={true}
234
      headerClassName="htLeft"
235
      licenseKey="non-commercial-and-evaluation"
236
    >
237
      <HotColumn data="itemName" type="text" width={130} />
238
      <HotColumn data="category" type="text" width={120} />
239
      <HotColumn data="leadEngineer" type="text" width={150} />
240
      <HotColumn
241
        data="quantity"
242
        type="numbro"
243
        width={150}
244
        className="htRight"
245
        numericFormat={{ pattern: '0,0', culture: 'en-US' }}
246
      />
247
      <HotColumn
248
        data="cost"
249
        type="numbro"
250
        width={120}
251
        className="htRight"
252
        numericFormat={{ pattern: '$0,0.00', culture: 'en-US' }}
253
      />
254
    </HotTable>
255
  );
256
};
257

258
export default ExampleComponent;

Overview

This guide shows how to create a custom numbro cell type using the Numbro library. Users can format numbers using the Numbro API.

Difficulty: Beginner Time: ~15 minutes Libraries: numbro

What You’ll Build

A cell that:

Displays numbers with locale-aware formatting via Numbro (e.g., $350,000.00)
Accepts numericFormat options for per-column formatting customization
Validates input using Handsontable’s built-in numeric validator
Automatically right-aligns numeric values

Prerequisites

1
npm install numbro

Import Dependencies

1
import Handsontable from 'handsontable/base';
2
import { registerAllModules } from 'handsontable/registry';
3
import { rendererFactory, getRenderer } from 'handsontable/renderers';
4
import { getEditor } from 'handsontable/editors';
5
import { getValidator } from 'handsontable/validators';
6
import { registerCellType } from 'handsontable/cellTypes';
7
import numbro from 'numbro';
8
// numbro ships no type declarations for its bundled language pack.
9
// @ts-expect-error -- untyped module
10
import languages from 'numbro/dist/languages.min.js';
11

12
registerAllModules();
13

14
Object.values(languages).forEach((language) => numbro.registerLanguage(language));

Why this matters:

numbro handles locale-aware number formatting (currencies, decimals, thousands separators)
rendererFactory creates a custom renderer that formats values with Numbro before displaying
Registering all Numbro languages upfront enables any culture to be used in numericFormat
Numbro’s bundled language pack ships no TypeScript declarations, so the import needs @ts-expect-error in a strict TypeScript project

Create the Numeric Helper

This helper determines whether a value should be treated as a number:

1
function isNumeric(value) {
2
  const type = typeof value;
3

4
  if (type === 'number') {
5
    return !isNaN(value) && isFinite(value);
6
  } else if (type === 'string') {
7
    if (value.length === 0) return false;
8
    if (value.length === 1) return /\d/.test(value);
9

10
    const delimiter = Array.from(new Set(['.']))
11
      .map(d => `\\${d}`)
12
      .join('|');
13

14
    return new RegExp(
15
      `^[+-]?(((${delimiter})?\\d+((${delimiter})\\d+)?(e[+-]?\\d+)?)|(0x[a-f\\d]+))$`, 'i'
16
    ).test(value.trim());
17
  } else if (type === 'object') {
18
    return !!value && typeof value.valueOf() === 'number' && !(value instanceof Date);
19
  }
20

21
  return false;
22
}

Create the Renderer

The renderer formats numeric values using Numbro and delegates to the built-in text renderer:

1
renderer: rendererFactory(({ hotInstance, td, row, col, prop, value, cellProperties }) => {
2
  if (isNumeric(value)) {
3
    const numericFormat = cellProperties.numericFormat;
4
    const cellCulture = numericFormat && numericFormat.culture || 'en-US';
5
    const cellFormatPattern = numericFormat && numericFormat.pattern;
6

7
    numbro.setLanguage(cellCulture);
8
    value = numbro(value).format(cellFormatPattern ?? '0');
9

10
    // Auto-apply htRight alignment for numeric cells
11
    td.dir = 'ltr';
12
  }
13

14
  getRenderer('text')(hotInstance, td, row, col, prop, value, cellProperties);
15
})

What’s happening:

Reads numericFormat.culture and numericFormat.pattern from cell properties
Formats the raw number using numbro(value).format(pattern)
Auto-applies htRight alignment unless another alignment class is set
Sets td.dir = 'ltr' for correct display in RTL layouts
Delegates to the text renderer for final DOM output

Complete Cell Type Definition

Put all the pieces together and register the cell type:
```
1
const cellTypeDefinition = {
2
  renderer: rendererFactory(({ hotInstance, td, row, col, prop, value, cellProperties }) => {
3
    // ... renderer code from Step 3 (see full example above)
4
  }),
5
  validator: getValidator('numeric'),
6
  editor: getEditor('numeric'),
7
};
8

9
registerCellType('numbro', cellTypeDefinition);
```
What’s happening:
- renderer: Formats numbers with Numbro and renders as right-aligned text
- validator: Uses the built-in numeric validator to reject non-numeric input
- editor: Uses the built-in numeric editor for input
- registerCellType: Registers the numbro cell type for use in column config

Use in Handsontable

1
registerCellType('numbro', cellTypeDefinition);
2

3
const hotOptions: Handsontable.GridSettings = {
4
  data,
5
  colHeaders: ['Item Name', 'Category', 'Lead Engineer', 'Quantity', 'Cost'],
6
  autoRowSize: true,
7
  rowHeaders: true,
8
  height: 'auto',
9
  width: '100%',
10
  autoWrapRow: true,
11
  headerClassName: 'htLeft',
12
  columns: [
13
    { data: 'itemName', type: 'text', width: 130 },
14
    { data: 'category', type: 'text', width: 120 },
15
    { data: 'leadEngineer', type: 'text', width: 150 },
16
    {
17
      data: 'quantity',
18
      type: 'numbro',
19
      width: 150,
20
      className: 'htRight',
21
      numericFormat: {
22
        pattern: '0,0',
23
        culture: 'en-US',
24
      },
25
    },
26
    {
27
      data: 'cost',
28
      type: 'numbro',
29
      width: 120,
30
      className: 'htRight',
31
      numericFormat: {
32
        pattern: '$0,0.00',
33
        culture: 'en-US',
34
      },
35
    },
36
  ],
37
  licenseKey: 'non-commercial-and-evaluation',
38
};
39

40
const hot = new Handsontable(container, hotOptions);

Key configuration:

type: 'numbro' - uses the custom cell type on Quantity and Cost columns
numericFormat.pattern - the Numbro format string (e.g., '$0,0.00' for currency, '0,0' for integers)
numericFormat.culture - the locale for formatting (e.g., 'en-US', 'de-DE')
headerClassName: 'htLeft' - left-aligns all column headers

How It Works - Complete Flow

Initial Render: Cell displays the raw number formatted by Numbro (e.g., 350000 becomes $350,000.00)
User clicks cell: The built-in numeric editor opens for editing
User enters number: Input is validated against the numeric validator
Validation: Non-numeric values are rejected; valid numbers are accepted
Save: The value is stored as a raw number and re-rendered with Numbro formatting

What you learned

You created a custom Numbro-based numeric cell type in Handsontable. You used rendererFactory to format numbers with Numbro before display, registered all Numbro language packs for locale support, and composed the cell type from a custom renderer with the built-in numeric validator and editor.

Next steps

Moment.js date - A custom cell type using another third-party library for date formatting.
Moment.js time - A custom cell type using Moment.js for time validation.
Pikaday - A date picker cell type using Pikaday and Moment.js.