Numbro

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
import languages from 'numbro/dist/languages.min.js';
9

10
// Register all Handsontable's modules.
11
registerAllModules();
12
Object.values(languages).forEach((language) => numbro.registerLanguage(language));
13

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

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

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

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

37
  return false;
38
}
39

40
/* start:skip-in-preview */
41
const data = [
42
  {
43
    id: 640329,
44
    itemName: 'Lunar Core',
45
    itemNo: 'XJ-12',
46
    leadEngineer: 'Ellen Ripley',
47
    cost: 350000,
48
    inStock: true,
49
    category: 'Lander',
50
    itemQuality: 87,
51
    origin: '🇺🇸 USA',
52
    quantity: 2,
53
    valueStock: 700000,
54
    repairable: false,
55
    supplierName: 'TechNova',
56
    restockDate: '2025-08-01',
57
    operationalStatus: 'Awaiting Parts',
58
  },
59
  {
60
    id: 863104,
61
    itemName: 'Zero Thrusters',
62
    itemNo: 'QL-54',
63
    leadEngineer: 'Sam Bell',
64
    cost: 450000,
65
    inStock: false,
66
    category: 'Propulsion',
67
    itemQuality: 0,
68
    origin: '🇩🇪 Germany',
69
    quantity: 0,
70
    valueStock: 0,
71
    repairable: true,
72
    supplierName: 'PropelMax',
73
    restockDate: '2025-09-15',
74
    operationalStatus: 'In Maintenance',
75
  },
76
  {
77
    id: 395603,
78
    itemName: 'EVA Suits',
79
    itemNo: 'PM-67',
80
    leadEngineer: 'Alex Rogan',
81
    cost: 150000,
82
    inStock: true,
83
    category: 'Equipment',
84
    itemQuality: 79,
85
    origin: '🇮🇹 Italy',
86
    quantity: 50,
87
    valueStock: 7500000,
88
    repairable: true,
89
    supplierName: 'SuitCraft',
90
    restockDate: '2025-10-05',
91
    operationalStatus: 'Ready for Testing',
92
  },
93
  {
94
    id: 679083,
95
    itemName: 'Solar Panels',
96
    itemNo: 'BW-09',
97
    leadEngineer: 'Dave Bowman',
98
    cost: 75000,
99
    inStock: true,
100
    category: 'Energy',
101
    itemQuality: 95,
102
    origin: '🇺🇸 USA',
103
    quantity: 10,
104
    valueStock: 750000,
105
    repairable: false,
106
    supplierName: 'SolarStream',
107
    restockDate: '2025-11-10',
108
    operationalStatus: 'Operational',
109
  },
110
  {
111
    id: 912663,
112
    itemName: 'Comm Array',
113
    itemNo: 'ZR-56',
114
    leadEngineer: 'Louise Banks',
115
    cost: 125000,
116
    inStock: false,
117
    category: 'Communication',
118
    itemQuality: 0,
119
    origin: '🇯🇵 Japan',
120
    quantity: 0,
121
    valueStock: 0,
122
    repairable: true,
123
    supplierName: 'CommTech',
124
    restockDate: '2025-12-20',
125
    operationalStatus: 'Decommissioned',
126
  },
127
  {
128
    id: 315806,
129
    itemName: 'Habitat Dome',
130
    itemNo: 'UJ-23',
131
    leadEngineer: 'Dr. Ryan Stone',
132
    cost: 1000000,
133
    inStock: true,
134
    category: 'Shelter',
135
    itemQuality: 93,
136
    origin: '🇨🇦 Canada',
137
    quantity: 3,
138
    valueStock: 3000000,
139
    repairable: false,
140
    supplierName: 'DomeInnovate',
141
    restockDate: '2026-01-25',
142
    operationalStatus: 'Operational',
143
  },
144
];
145

146
/* end:skip-in-preview */
147
// Get the DOM element with the ID 'example1' where the Handsontable will be rendered
148
const container = document.querySelector('#example1');
149
const cellTypeDefinition = {
150
  renderer: rendererFactory(({ hotInstance, td, row, col, prop, value, cellProperties }) => {
151
    if (isNumeric(value)) {
152
      let classArr = [];
153

154
      if (Array.isArray(cellProperties.className)) {
155
        classArr = cellProperties.className;
156
      } else {
157
        const className = cellProperties.className ?? '';
158

159
        if (className.length) {
160
          classArr = className.split(' ');
161
        }
162
      }
163

164
      const numericFormat = cellProperties.numericFormat;
165
      const cellCulture = (numericFormat && numericFormat.culture) || 'en-US';
166
      const cellFormatPattern = numericFormat && numericFormat.pattern;
167

168
      // Register the language if it's not already registered
169
      if (cellCulture && !numbro.languages()[cellCulture]) {
170
        const shortTag = cellCulture.replace('-', '');
171
        const langData = numbro.allLanguages ? numbro.allLanguages[cellCulture] : numbro[shortTag];
172

173
        if (langData) {
174
          numbro.registerLanguage(langData);
175
        }
176
      }
177

178
      numbro.setLanguage(cellCulture);
179
      value = numbro(value).format(cellFormatPattern ?? '0');
180

181
      if (
182
        classArr.indexOf('htLeft') < 0 &&
183
        classArr.indexOf('htCenter') < 0 &&
184
        classArr.indexOf('htRight') < 0 &&
185
        classArr.indexOf('htJustify') < 0
186
      ) {
187
        classArr.push('htRight');
188
      }
189

190
      if (classArr.indexOf('htNumeric') < 0) {
191
        classArr.push('htNumeric');
192
      }
193

194
      cellProperties.className = classArr.join(' ');
195
      td.dir = 'ltr';
196
    }
197

198
    getRenderer('text')(hotInstance, td, row, col, prop, value, cellProperties);
199
  }),
200
  validator: getValidator('numeric'),
201
  editor: getEditor('numeric'),
202
};
203

204
registerCellType('numbro', cellTypeDefinition);
205

206
// Define configuration options for the Handsontable
207
const hotOptions = {
208
  data,
209
  colHeaders: ['Item Name', 'Category', 'Lead Engineer', 'Quantity', 'Cost'],
210
  autoRowSize: true,
211
  rowHeaders: true,
212
  height: 'auto',
213
  width: '100%',
214
  autoWrapRow: true,
215
  headerClassName: 'htLeft',
216
  columns: [
217
    { data: 'itemName', type: 'text', width: 130 },
218
    { data: 'category', type: 'text', width: 120 },
219
    { data: 'leadEngineer', type: 'text', width: 150 },
220
    {
221
      data: 'quantity',
222
      type: 'numbro',
223
      width: 150,
224
      className: 'htRight',
225
      numericFormat: {
226
        pattern: '0,0',
227
        culture: 'en-US',
228
      },
229
    },
230
    {
231
      data: 'cost',
232
      type: 'numbro',
233
      width: 120,
234
      className: 'htRight',
235
      numericFormat: {
236
        pattern: '$0,0.00',
237
        culture: 'en-US',
238
      },
239
    },
240
  ],
241
  licenseKey: 'non-commercial-and-evaluation',
242
};
243

244
// Initialize the Handsontable instance with the specified configuration options
245
// eslint-disable-next-line no-unused-vars
246
const hot = new Handsontable(container, hotOptions);

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
import languages from 'numbro/dist/languages.min.js';
9

10
// Register all Handsontable's modules.
11
registerAllModules();
12

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

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

18
  if (type === 'number') {
19
    return !isNaN(value) && isFinite(value);
20

21
  } else if (type === 'string') {
22
    if (value.length === 0) {
23
      return false;
24

25
    } else if (value.length === 1) {
26
      return /\d/.test(value);
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')
34
      .test(value.trim());
35

36
  } else if (type === 'object') {
37
    return !!value && typeof value.valueOf() === 'number' && !(value instanceof Date);
38
  }
39

40
  return false;
41
}
42

43
/* start:skip-in-preview */
44
const data = [
45
  {
46
    id: 640329,
47
    itemName: 'Lunar Core',
48
    itemNo: 'XJ-12',
49
    leadEngineer: 'Ellen Ripley',
50
    cost: 350000,
51
    inStock: true,
52
    category: 'Lander',
53
    itemQuality: 87,
54
    origin: '🇺🇸 USA',
55
    quantity: 2,
56
    valueStock: 700000,
57
    repairable: false,
58
    supplierName: 'TechNova',
59
    restockDate: '2025-08-01',
60
    operationalStatus: 'Awaiting Parts',
61
  },
62
  {
63
    id: 863104,
64
    itemName: 'Zero Thrusters',
65
    itemNo: 'QL-54',
66
    leadEngineer: 'Sam Bell',
67
    cost: 450000,
68
    inStock: false,
69
    category: 'Propulsion',
70
    itemQuality: 0,
71
    origin: '🇩🇪 Germany',
72
    quantity: 0,
73
    valueStock: 0,
74
    repairable: true,
75
    supplierName: 'PropelMax',
76
    restockDate: '2025-09-15',
77
    operationalStatus: 'In Maintenance',
78
  },
79
  {
80
    id: 395603,
81
    itemName: 'EVA Suits',
82
    itemNo: 'PM-67',
83
    leadEngineer: 'Alex Rogan',
84
    cost: 150000,
85
    inStock: true,
86
    category: 'Equipment',
87
    itemQuality: 79,
88
    origin: '🇮🇹 Italy',
89
    quantity: 50,
90
    valueStock: 7500000,
91
    repairable: true,
92
    supplierName: 'SuitCraft',
93
    restockDate: '2025-10-05',
94
    operationalStatus: 'Ready for Testing',
95
  },
96
  {
97
    id: 679083,
98
    itemName: 'Solar Panels',
99
    itemNo: 'BW-09',
100
    leadEngineer: 'Dave Bowman',
101
    cost: 75000,
102
    inStock: true,
103
    category: 'Energy',
104
    itemQuality: 95,
105
    origin: '🇺🇸 USA',
106
    quantity: 10,
107
    valueStock: 750000,
108
    repairable: false,
109
    supplierName: 'SolarStream',
110
    restockDate: '2025-11-10',
111
    operationalStatus: 'Operational',
112
  },
113
  {
114
    id: 912663,
115
    itemName: 'Comm Array',
116
    itemNo: 'ZR-56',
117
    leadEngineer: 'Louise Banks',
118
    cost: 125000,
119
    inStock: false,
120
    category: 'Communication',
121
    itemQuality: 0,
122
    origin: '🇯🇵 Japan',
123
    quantity: 0,
124
    valueStock: 0,
125
    repairable: true,
126
    supplierName: 'CommTech',
127
    restockDate: '2025-12-20',
128
    operationalStatus: 'Decommissioned',
129
  },
130
  {
131
    id: 315806,
132
    itemName: 'Habitat Dome',
133
    itemNo: 'UJ-23',
134
    leadEngineer: 'Dr. Ryan Stone',
135
    cost: 1000000,
136
    inStock: true,
137
    category: 'Shelter',
138
    itemQuality: 93,
139
    origin: '🇨🇦 Canada',
140
    quantity: 3,
141
    valueStock: 3000000,
142
    repairable: false,
143
    supplierName: 'DomeInnovate',
144
    restockDate: '2026-01-25',
145
    operationalStatus: 'Operational',
146
  },
147
];
148
/* end:skip-in-preview */
149
// Get the DOM element with the ID 'example1' where the Handsontable will be rendered
150
const container = document.querySelector('#example1')!;
151
const cellTypeDefinition = {
152
  renderer: rendererFactory(({ hotInstance, td, row, col, prop, value, cellProperties }) => {
153
    if (isNumeric(value)) {
154
      let classArr = [];
155

156
      if (Array.isArray(cellProperties.className)) {
157
        classArr = cellProperties.className;
158
      } else {
159
        const className = cellProperties.className ?? '';
160

161
        if (className.length) {
162
          classArr = className.split(' ');
163
        }
164
      }
165

166
      const numericFormat = cellProperties.numericFormat;
167
      const cellCulture = numericFormat && numericFormat.culture || 'en-US';
168
      const cellFormatPattern = numericFormat && numericFormat.pattern;
169

170
      // Register the language if it's not already registered
171
      if (cellCulture && !numbro.languages()[cellCulture]) {
172
        const shortTag = cellCulture.replace('-', '');
173
        const langData = numbro.allLanguages ? numbro.allLanguages[cellCulture] : numbro[shortTag];
174

175
        if (langData) {
176
          numbro.registerLanguage(langData);
177
        }
178
      }
179

180
      numbro.setLanguage(cellCulture);
181

182
      value = numbro(value).format(cellFormatPattern ?? '0');
183

184
      if (
185
        classArr.indexOf('htLeft') < 0 &&
186
        classArr.indexOf('htCenter') < 0 &&
187
        classArr.indexOf('htRight') < 0 &&
188
        classArr.indexOf('htJustify') < 0
189
      ) {
190
        classArr.push('htRight');
191
      }
192

193
      if (classArr.indexOf('htNumeric') < 0) {
194
        classArr.push('htNumeric');
195
      }
196

197
      cellProperties.className = classArr.join(' ');
198
      td.dir = 'ltr';
199
    }
200

201
    getRenderer('text')(hotInstance, td, row, col, prop, value, cellProperties);
202
  }),
203
  validator: getValidator('numeric'),
204
  editor: getEditor('numeric'),
205
};
206

207
registerCellType('numbro', cellTypeDefinition);
208

209
// Define configuration options for the Handsontable
210
const hotOptions: Handsontable.GridSettings = {
211
  data,
212
  colHeaders: ['Item Name', 'Category', 'Lead Engineer', 'Quantity', 'Cost'],
213
  autoRowSize: true,
214
  rowHeaders: true,
215
  height: 'auto',
216
  width: '100%',
217
  autoWrapRow: true,
218
  headerClassName: 'htLeft',
219
  columns: [
220
    { data: 'itemName', type: 'text', width: 130 },
221
    { data: 'category', type: 'text', width: 120 },
222
    { data: 'leadEngineer', type: 'text', width: 150 },
223
    {
224
      data: 'quantity',
225
      type: 'numbro',
226
      width: 150,
227
      className: 'htRight',
228
      numericFormat: {
229
        pattern: '0,0',
230
        culture: 'en-US',
231
      },
232
    },
233
    {
234
      data: 'cost',
235
      type: 'numbro',
236
      width: 120,
237
      className: 'htRight',
238
      numericFormat: {
239
        pattern: '$0,0.00',
240
        culture: 'en-US',
241
      },
242
    },
243
  ],
244
  licenseKey: 'non-commercial-and-evaluation',
245
};
246

247
// Initialize the Handsontable instance with the specified configuration options
248
// eslint-disable-next-line no-unused-vars
249
const hot = new Handsontable(container, hotOptions);

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
import languages from 'numbro/dist/languages.min.js';
9

10
registerAllModules();
11

12
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

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