Pikaday

This tutorial shows you how to integrate the Pikaday date picker as a custom Handsontable cell editor, with portal positioning and Moment.js formatting. This recipe also serves as a migration guide for users moving away from the built-in date cell type.

1
import Handsontable from 'handsontable/base';
2
import { registerAllModules } from 'handsontable/registry';
3
import moment from 'moment';
4
import Pikaday from 'pikaday';
5
import 'pikaday/css/pikaday.css';
6
import { editorFactory } from 'handsontable/editors';
7
import { rendererFactory } from 'handsontable/renderers';
8

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

12
const DATE_FORMAT_US = 'MM/DD/YYYY';
13
const DEFAULT_DATE_FORMAT = DATE_FORMAT_US;
14
/* start:skip-in-preview */
15
const inputData = [
16
  {
17
    id: 640329,
18
    itemName: 'Lunar Core',
19
    itemNo: 'XJ-12',
20
    leadEngineer: 'Ellen Ripley',
21
    cost: 350000,
22
    inStock: true,
23
    category: 'Lander',
24
    itemQuality: 87,
25
    origin: '🇺🇸 USA',
26
    quantity: 2,
27
    valueStock: 700000,
28
    repairable: false,
29
    supplierName: 'TechNova',
30
    restockDate: '2025-08-01',
31
    operationalStatus: 'Awaiting Parts',
32
  },
33
  {
34
    id: 863104,
35
    itemName: 'Zero Thrusters',
36
    itemNo: 'QL-54',
37
    leadEngineer: 'Sam Bell',
38
    cost: 450000,
39
    inStock: false,
40
    category: 'Propulsion',
41
    itemQuality: 0,
42
    origin: '🇩🇪 Germany',
43
    quantity: 0,
44
    valueStock: 0,
45
    repairable: true,
46
    supplierName: 'PropelMax',
47
    restockDate: '2025-09-15',
48
    operationalStatus: 'In Maintenance',
49
  },
50
  {
51
    id: 395603,
52
    itemName: 'EVA Suits',
53
    itemNo: 'PM-67',
54
    leadEngineer: 'Alex Rogan',
55
    cost: 150000,
56
    inStock: true,
57
    category: 'Equipment',
58
    itemQuality: 79,
59
    origin: '🇮🇹 Italy',
60
    quantity: 50,
61
    valueStock: 7500000,
62
    repairable: true,
63
    supplierName: 'SuitCraft',
64
    restockDate: '2025-10-05',
65
    operationalStatus: 'Ready for Testing',
66
  },
67
  {
68
    id: 679083,
69
    itemName: 'Solar Panels',
70
    itemNo: 'BW-09',
71
    leadEngineer: 'Dave Bowman',
72
    cost: 75000,
73
    inStock: true,
74
    category: 'Energy',
75
    itemQuality: 95,
76
    origin: '🇺🇸 USA',
77
    quantity: 10,
78
    valueStock: 750000,
79
    repairable: false,
80
    supplierName: 'SolarStream',
81
    restockDate: '2025-11-10',
82
    operationalStatus: 'Operational',
83
  },
84
  {
85
    id: 912663,
86
    itemName: 'Comm Array',
87
    itemNo: 'ZR-56',
88
    leadEngineer: 'Louise Banks',
89
    cost: 125000,
90
    inStock: false,
91
    category: 'Communication',
92
    itemQuality: 0,
93
    origin: '🇯🇵 Japan',
94
    quantity: 0,
95
    valueStock: 0,
96
    repairable: true,
97
    supplierName: 'CommTech',
98
    restockDate: '2025-12-20',
99
    operationalStatus: 'Decommissioned',
100
  },
101
  {
102
    id: 315806,
103
    itemName: 'Habitat Dome',
104
    itemNo: 'UJ-23',
105
    leadEngineer: 'Dr. Ryan Stone',
106
    cost: 1000000,
107
    inStock: true,
108
    category: 'Shelter',
109
    itemQuality: 93,
110
    origin: '🇨🇦 Canada',
111
    quantity: 3,
112
    valueStock: 3000000,
113
    repairable: false,
114
    supplierName: 'DomeInnovate',
115
    restockDate: '2026-01-25',
116
    operationalStatus: 'Operational',
117
  },
118
  {
119
    id: 954632,
120
    itemName: 'Oxygen Unit',
121
    itemNo: 'FK-87',
122
    leadEngineer: 'Dr. Grace Augustine',
123
    cost: 600000,
124
    inStock: true,
125
    category: 'Life Support',
126
    itemQuality: 85,
127
    origin: '🇺🇸 USA',
128
    quantity: 15,
129
    valueStock: 9000000,
130
    repairable: true,
131
    supplierName: 'OxyGenius',
132
    restockDate: '2026-03-02',
133
    operationalStatus: 'Awaiting Parts',
134
  },
135
  {
136
    id: 734944,
137
    itemName: 'Processing Rig',
138
    itemNo: 'LK-13',
139
    leadEngineer: 'Jake Sully',
140
    cost: 350000,
141
    inStock: true,
142
    category: 'Mining',
143
    itemQuality: 81,
144
    origin: '🇦🇺 Australia',
145
    quantity: 25,
146
    valueStock: 8750000,
147
    repairable: true,
148
    supplierName: 'RigTech',
149
    restockDate: '2026-04-15',
150
    operationalStatus: 'Ready for Testing',
151
  },
152
  {
153
    id: 834662,
154
    itemName: 'Navigation',
155
    itemNo: 'XP-24',
156
    leadEngineer: 'Dr. Ellie Arroway',
157
    cost: 450000,
158
    inStock: true,
159
    category: 'Navigation',
160
    itemQuality: 89,
161
    origin: '🇫🇷 France',
162
    quantity: 8,
163
    valueStock: 3600000,
164
    repairable: false,
165
    supplierName: 'NavSolutions',
166
    restockDate: '2026-05-30',
167
    operationalStatus: 'In Maintenance',
168
  },
169
  {
170
    id: 714329,
171
    itemName: 'Surveyor Arm',
172
    itemNo: 'QA-86',
173
    leadEngineer: 'Mark Watney',
174
    cost: 100000,
175
    inStock: true,
176
    category: 'Exploration',
177
    itemQuality: 78,
178
    origin: '🇺🇸 USA',
179
    quantity: 40,
180
    valueStock: 4000000,
181
    repairable: true,
182
    supplierName: 'ExploreTech',
183
    restockDate: '2026-07-12',
184
    operationalStatus: 'Decommissioned',
185
  },
186
];
187

188
const data = inputData.map((item) => ({
189
  ...item,
190
  restockDate: moment(new Date(item.restockDate)).format(DATE_FORMAT_US),
191
}));
192

193
/* end:skip-in-preview */
194
// Get the DOM element with the ID 'example1' where the Handsontable will be rendered
195
const container = document.querySelector('#example1');
196
const cellDefinition = {
197
  renderer: rendererFactory(({ td, value, cellProperties }) => {
198
    td.innerText = moment(new Date(value), cellProperties.renderFormat).format(cellProperties.renderFormat);
199
  }),
200
  editor: editorFactory({
201
    position: 'portal',
202
    shortcuts: [
203
      {
204
        keys: [['ArrowLeft']],
205
        callback: (editor, _event) => {
206
          // @ts-ignore
207
          editor.pickaday.adjustDate('subtract', 1);
208
          _event.preventDefault();
209
        },
210
      },
211
      {
212
        keys: [['ArrowRight']],
213
        callback: (editor, _event) => {
214
          // @ts-ignore
215
          editor.pickaday.adjustDate('add', 1);
216
          _event.preventDefault();
217
        },
218
      },
219
      {
220
        keys: [['ArrowUp']],
221
        callback: (editor, _event) => {
222
          // @ts-ignore
223
          editor.pickaday.adjustDate('subtract', 7);
224
          _event.preventDefault();
225
        },
226
      },
227
      {
228
        keys: [['ArrowDown']],
229
        callback: (editor, _event) => {
230
          // @ts-ignore
231
          editor.pickaday.adjustDate('add', 7);
232
          _event.preventDefault();
233
        },
234
      },
235
    ],
236
    init(editor) {
237
      editor.parentDestroyed = false;
238
      // create the input element on init. This is a text input that color picker will be attached to.
239
      editor.input = editor.hot.rootDocument.createElement('INPUT');
240
      editor.datePicker = editor.container;
241
      /**
242
       * Prevent recognizing clicking on datepicker as clicking outside of table.
243
       */
244
      editor.hot.rootDocument.addEventListener('mousedown', (event) => {
245
        if (event.target && event.target.classList.contains('pika-day')) {
246
          editor.hideDatepicker(editor);
247
        }
248
      });
249
    },
250
    getDatePickerConfig(editor) {
251
      const htInput = editor.input;
252
      const options = {};
253

254
      if (editor.cellProperties && editor.cellProperties.datePickerConfig) {
255
        Object.assign(options, editor.cellProperties.datePickerConfig);
256
      }
257

258
      const origOnSelect = options.onSelect;
259
      const origOnClose = options.onClose;
260

261
      options.field = htInput;
262
      options.trigger = htInput;
263
      options.container = editor.datePicker;
264
      options.bound = false;
265
      options.keyboardInput = false;
266
      options.format = options.format ?? editor.getDateFormat(editor);
267
      // Pikaday only formats and parses through Moment.js when it can reach `moment` itself, which
268
      // it cannot under a bundler. These two hooks take precedence over its internal path, so the
269
      // `format` above is honored both on display and on input.
270
      options.toString = (date, format) => moment(date).format(format);
271
      options.parse = (dateString, format) => moment(dateString, format).toDate();
272
      options.reposition = options.reposition || false;
273
      // Set the RTL to `false`. Due to the https://github.com/Pikaday/Pikaday/issues/647 bug, the layout direction
274
      // of the date picker is controlled by juggling the "dir" attribute of the root date picker element.
275
      options.isRTL = false;
276
      options.onSelect = function (date) {
277
        let dateStr;
278

279
        if (!isNaN(date.getTime())) {
280
          dateStr = moment(date).format(editor.getDateFormat(editor));
281
        }
282

283
        editor.setValue(dateStr);
284

285
        if (origOnSelect) {
286
          origOnSelect.call(editor.pickaday, date);
287
        }
288

289
        if (editor.hot.rootWindow.matchMedia('(pointer: coarse)').matches) {
290
          editor.hideDatepicker(editor);
291
        }
292
      };
293
      options.onClose = () => {
294
        if (!editor.parentDestroyed) {
295
          editor.finishEditing(false);
296
        }
297

298
        if (origOnClose) {
299
          origOnClose();
300
        }
301
      };
302

303
      return options;
304
    },
305
    hideDatepicker(editor) {
306
      editor.pickaday?.hide();
307
    },
308
    showDatepicker(editor, event) {
309
      const dateFormat = editor.getDateFormat(editor);
310
      // TODO: view is not exported in the handsontable library d.ts, so we need to use @ts-ignore
311
      // @ts-ignore
312
      const isMouseDown = editor.hot.view.isMouseDown();
313
      // A printable character reports a single-character `key`; anything else is a function key.
314
      const isMeta = event && 'key' in event ? event.key.length > 1 : false;
315

316
      let dateStr;
317

318
      editor.datePicker.style.display = 'block';
319
      editor.pickaday = new Pikaday(editor.getDatePickerConfig(editor));
320

321

322
      // TODO: _onInputFocus is not exported in the pikaday library d.ts, so we need to use @ts-ignore
323
      // @ts-ignore
324
      editor.pickaday._onInputFocus = function () {};
325

326
      if (editor.originalValue) {
327
        dateStr = editor.originalValue;
328

329
        if (moment(dateStr, dateFormat, true).isValid()) {
330
          editor.pickaday.setDate(moment(dateStr, dateFormat).toDate(), true);
331
        }
332

333
        // workaround for date/time cells - pikaday resets the cell value to 12:00 AM by default, this will overwrite the value.
334
        if (editor.getValue() !== editor.originalValue) {
335
          editor.setValue(editor.originalValue);
336
        }
337

338
        if (!isMeta && !isMouseDown) {
339
          editor.setValue('');
340
        }
341
      } else if (editor.cellProperties.defaultDate) {
342
        dateStr = editor.cellProperties.defaultDate;
343

344
        if (moment(dateStr, dateFormat, true).isValid()) {
345
          editor.pickaday.setDate(moment(dateStr, dateFormat).toDate(), true);
346
        }
347

348
        if (!isMeta && !isMouseDown) {
349
          editor.setValue('');
350
        }
351
      } else {
352
        // if a default date is not defined, set a soft-default-date: display the current day and month in the
353
        // datepicker, but don't fill the editor input
354
        editor.pickaday.gotoToday();
355
      }
356
    },
357
    afterClose(editor) {
358
      if (editor.pickaday?.destroy) {
359
        editor.pickaday.destroy();
360
      }
361
    },
362
    afterOpen(editor, event) {
363
      const cellRect = editor.TD.getBoundingClientRect();
364

365
      editor.input.style.width = `${cellRect.width}px`;
366
      editor.input.style.height = `${cellRect.height}px`;
367
      editor.showDatepicker(editor, event);
368
    },
369
    getValue(editor) {
370
      return editor.input.value;
371
    },
372
    setValue(editor, value) {
373
      editor.input.value = value;
374
    },
375
    getDateFormat(editor) {
376
      return editor.cellProperties.dateFormat ?? DEFAULT_DATE_FORMAT;
377
    },
378
  }),
379
};
380

381
// Define configuration options for the Handsontable
382
const hotOptions = {
383
  data,
384
  height: 'auto',
385
  colHeaders: ['Item Name', 'Category', 'Lead Engineer', 'Restock Date', 'Cost'],
386
  autoRowSize: true,
387
  rowHeaders: true,
388
  width: '100%',
389
  autoWrapRow: true,
390
  headerClassName: 'htLeft',
391
  columns: [
392
    { data: 'itemName', type: 'text', width: 130 },
393
    { data: 'category', type: 'text', width: 120 },
394
    { data: 'leadEngineer', type: 'text', width: 150 },
395
    {
396
      data: 'restockDate',
397
      width: 150,
398
      allowInvalid: false,
399
      ...cellDefinition,
400
      renderFormat: DATE_FORMAT_US,
401
      dateFormat: DATE_FORMAT_US,
402
      defaultDate: '01/01/2020',
403
      datePickerConfig: {
404
        firstDay: 0,
405
        showWeekNumber: true,
406
        disableDayFn(date) {
407
          return date.getDay() === 0 || date.getDay() === 6;
408
        },
409
      },
410
    },
411
    {
412
      data: 'cost',
413
      type: 'numeric',
414
      width: 120,
415
      className: 'htRight',
416
      locale: 'en-US',
417
      numericFormat: {
418
        style: 'currency',
419
        currency: 'USD',
420
        minimumFractionDigits: 2,
421
      },
422
    },
423
  ],
424
  licenseKey: 'non-commercial-and-evaluation',
425
};
426

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

1
import Handsontable from "handsontable/base";
2
import { registerAllModules } from "handsontable/registry";
3
import moment from "moment";
4
import Pikaday from "pikaday";
5
import "pikaday/css/pikaday.css";
6
import { CellProperties } from "handsontable/settings";
7
import { editorFactory } from "handsontable/editors";
8
import { rendererFactory } from "handsontable/renderers";
9
// Register all Handsontable's modules.
10
registerAllModules();
11

12
const DATE_FORMAT_US = "MM/DD/YYYY";
13
const DEFAULT_DATE_FORMAT = DATE_FORMAT_US;
14

15
/* start:skip-in-preview */
16

17
const inputData = [
18
  {
19
    id: 640329,
20
    itemName: "Lunar Core",
21
    itemNo: "XJ-12",
22
    leadEngineer: "Ellen Ripley",
23
    cost: 350000,
24
    inStock: true,
25
    category: "Lander",
26
    itemQuality: 87,
27
    origin: "🇺🇸 USA",
28
    quantity: 2,
29
    valueStock: 700000,
30
    repairable: false,
31
    supplierName: "TechNova",
32
    restockDate: "2025-08-01",
33
    operationalStatus: "Awaiting Parts",
34
  },
35
  {
36
    id: 863104,
37
    itemName: "Zero Thrusters",
38
    itemNo: "QL-54",
39
    leadEngineer: "Sam Bell",
40
    cost: 450000,
41
    inStock: false,
42
    category: "Propulsion",
43
    itemQuality: 0,
44
    origin: "🇩🇪 Germany",
45
    quantity: 0,
46
    valueStock: 0,
47
    repairable: true,
48
    supplierName: "PropelMax",
49
    restockDate: "2025-09-15",
50
    operationalStatus: "In Maintenance",
51
  },
52
  {
53
    id: 395603,
54
    itemName: "EVA Suits",
55
    itemNo: "PM-67",
56
    leadEngineer: "Alex Rogan",
57
    cost: 150000,
58
    inStock: true,
59
    category: "Equipment",
60
    itemQuality: 79,
61
    origin: "🇮🇹 Italy",
62
    quantity: 50,
63
    valueStock: 7500000,
64
    repairable: true,
65
    supplierName: "SuitCraft",
66
    restockDate: "2025-10-05",
67
    operationalStatus: "Ready for Testing",
68
  },
69
  {
70
    id: 679083,
71
    itemName: "Solar Panels",
72
    itemNo: "BW-09",
73
    leadEngineer: "Dave Bowman",
74
    cost: 75000,
75
    inStock: true,
76
    category: "Energy",
77
    itemQuality: 95,
78
    origin: "🇺🇸 USA",
79
    quantity: 10,
80
    valueStock: 750000,
81
    repairable: false,
82
    supplierName: "SolarStream",
83
    restockDate: "2025-11-10",
84
    operationalStatus: "Operational",
85
  },
86
  {
87
    id: 912663,
88
    itemName: "Comm Array",
89
    itemNo: "ZR-56",
90
    leadEngineer: "Louise Banks",
91
    cost: 125000,
92
    inStock: false,
93
    category: "Communication",
94
    itemQuality: 0,
95
    origin: "🇯🇵 Japan",
96
    quantity: 0,
97
    valueStock: 0,
98
    repairable: true,
99
    supplierName: "CommTech",
100
    restockDate: "2025-12-20",
101
    operationalStatus: "Decommissioned",
102
  },
103
  {
104
    id: 315806,
105
    itemName: "Habitat Dome",
106
    itemNo: "UJ-23",
107
    leadEngineer: "Dr. Ryan Stone",
108
    cost: 1000000,
109
    inStock: true,
110
    category: "Shelter",
111
    itemQuality: 93,
112
    origin: "🇨🇦 Canada",
113
    quantity: 3,
114
    valueStock: 3000000,
115
    repairable: false,
116
    supplierName: "DomeInnovate",
117
    restockDate: "2026-01-25",
118
    operationalStatus: "Operational",
119
  },
120
  {
121
    id: 954632,
122
    itemName: "Oxygen Unit",
123
    itemNo: "FK-87",
124
    leadEngineer: "Dr. Grace Augustine",
125
    cost: 600000,
126
    inStock: true,
127
    category: "Life Support",
128
    itemQuality: 85,
129
    origin: "🇺🇸 USA",
130
    quantity: 15,
131
    valueStock: 9000000,
132
    repairable: true,
133
    supplierName: "OxyGenius",
134
    restockDate: "2026-03-02",
135
    operationalStatus: "Awaiting Parts",
136
  },
137
  {
138
    id: 734944,
139
    itemName: "Processing Rig",
140
    itemNo: "LK-13",
141
    leadEngineer: "Jake Sully",
142
    cost: 350000,
143
    inStock: true,
144
    category: "Mining",
145
    itemQuality: 81,
146
    origin: "🇦🇺 Australia",
147
    quantity: 25,
148
    valueStock: 8750000,
149
    repairable: true,
150
    supplierName: "RigTech",
151
    restockDate: "2026-04-15",
152
    operationalStatus: "Ready for Testing",
153
  },
154
  {
155
    id: 834662,
156
    itemName: "Navigation",
157
    itemNo: "XP-24",
158
    leadEngineer: "Dr. Ellie Arroway",
159
    cost: 450000,
160
    inStock: true,
161
    category: "Navigation",
162
    itemQuality: 89,
163
    origin: "🇫🇷 France",
164
    quantity: 8,
165
    valueStock: 3600000,
166
    repairable: false,
167
    supplierName: "NavSolutions",
168
    restockDate: "2026-05-30",
169
    operationalStatus: "In Maintenance",
170
  },
171
  {
172
    id: 714329,
173
    itemName: "Surveyor Arm",
174
    itemNo: "QA-86",
175
    leadEngineer: "Mark Watney",
176
    cost: 100000,
177
    inStock: true,
178
    category: "Exploration",
179
    itemQuality: 78,
180
    origin: "🇺🇸 USA",
181
    quantity: 40,
182
    valueStock: 4000000,
183
    repairable: true,
184
    supplierName: "ExploreTech",
185
    restockDate: "2026-07-12",
186
    operationalStatus: "Decommissioned",
187
  },
188
];
189

190
const data = inputData.map((item) => ({
191
  ...item,
192
  restockDate: moment(new Date(item.restockDate)).format(DATE_FORMAT_US),
193
}));
194

195
/* end:skip-in-preview */
196

197
// Get the DOM element with the ID 'example1' where the Handsontable will be rendered
198
const container = document.querySelector("#example1")!;
199

200
type EditorPropertiesType = {
201
  input: HTMLInputElement;
202
  pickaday: Pikaday;
203
  datePicker: HTMLDivElement;
204
  parentDestroyed: boolean;
205
};
206

207
// Helper type to extract the editor type from factory callbacks
208
type FactoryEditorType<TProps, TMethods> = Parameters<
209
  Parameters<
210
    typeof editorFactory<TProps, TMethods>
211
  >[0]["init"]
212
>[0];
213

214
type EditorMethodsType = {
215
  showDatepicker: (
216
    editor: FactoryEditorType<EditorPropertiesType, EditorMethodsType>,
217
    event: Event | undefined,
218
  ) => void;
219
  hideDatepicker: (
220
    editor: FactoryEditorType<EditorPropertiesType, EditorMethodsType>,
221
  ) => void;
222
  getDatePickerConfig: (
223
    editor: FactoryEditorType<EditorPropertiesType, EditorMethodsType>,
224
  ) => Pikaday.PikadayOptions;
225
  getDateFormat: (
226
    editor: FactoryEditorType<EditorPropertiesType, EditorMethodsType>,
227
  ) => string;
228
};
229

230
const cellDefinition: Pick<
231
  CellProperties,
232
  "renderer" | "validator" | "editor"
233
> = {
234
  renderer: rendererFactory(({ td, value, cellProperties }) => {
235
    td.innerText = moment(new Date(value), cellProperties.renderFormat).format(
236
      cellProperties.renderFormat,
237
    );
238
  }),
239

240
  editor: editorFactory<
241
    EditorPropertiesType,
242
    EditorMethodsType
243
  >({
244
    position: "portal",
245
    shortcuts: [{
246
      keys: [["ArrowLeft"]],
247
      callback: (editor, _event) => {
248
        //@ts-ignore
249
        editor.pickaday.adjustDate("subtract", 1);
250
        _event.preventDefault();
251
      },
252
    }, {
253
      keys: [["ArrowRight"]],
254
      callback: (editor, _event) => {
255
        //@ts-ignore
256
        editor.pickaday.adjustDate("add", 1);
257
        _event.preventDefault();
258
      },
259
    }, {
260
      keys: [["ArrowUp"]],
261
      callback: (editor, _event) => {
262
        //@ts-ignore
263
        editor.pickaday.adjustDate("subtract", 7);
264
        _event.preventDefault();
265
      },
266
    }, {
267
      keys: [["ArrowDown"]],
268
      callback: (editor, _event) => {
269
        //@ts-ignore
270
        editor.pickaday.adjustDate("add", 7);
271
        _event.preventDefault();
272
      },
273
    }],
274
    init(editor) {
275
      editor.parentDestroyed = false;
276
      // create the input element on init. This is a text input that color picker will be attached to.
277
      editor.input = editor.hot.rootDocument.createElement(
278
        "INPUT",
279
      ) as HTMLInputElement;
280

281
      editor.datePicker = editor.container;
282

283
      /**
284
       * Prevent recognizing clicking on datepicker as clicking outside of table.
285
       */
286
      editor.hot.rootDocument.addEventListener("mousedown", (event) => {
287
        if (
288
          event.target &&
289
          (event.target as HTMLElement).classList.contains("pika-day")
290
        ) {
291
          editor.hideDatepicker(editor);
292
        }
293
      });
294
    },
295
    getDatePickerConfig(editor) {
296
      const htInput = editor.input;
297
      const options: Pikaday.PikadayOptions = {};
298

299
      if (editor.cellProperties && editor.cellProperties.datePickerConfig) {
300
        Object.assign(options, editor.cellProperties.datePickerConfig);
301
      }
302
      const origOnSelect = options.onSelect;
303
      const origOnClose = options.onClose;
304

305
      options.field = htInput;
306
      options.trigger = htInput;
307
      options.container = editor.datePicker;
308
      options.bound = false;
309
      options.keyboardInput = false;
310
      options.format = options.format ?? editor.getDateFormat(editor);
311
      // Pikaday only formats and parses through Moment.js when it can reach `moment` itself, which
312
      // it cannot under a bundler. These two hooks take precedence over its internal path, so the
313
      // `format` above is honored both on display and on input.
314
      options.toString = (date, format) => moment(date).format(format);
315
      options.parse = (dateString, format) =>
316
        moment(dateString, format).toDate();
317
      options.reposition = options.reposition || false;
318
      // Set the RTL to `false`. Due to the https://github.com/Pikaday/Pikaday/issues/647 bug, the layout direction
319
      // of the date picker is controlled by juggling the "dir" attribute of the root date picker element.
320
      options.isRTL = false;
321
      options.onSelect = function (date) {
322
        let dateStr;
323

324
        if (!isNaN(date.getTime())) {
325
          dateStr = moment(date).format(editor.getDateFormat(editor));
326
        }
327
        editor.setValue(dateStr);
328

329
        if (origOnSelect) {
330
          origOnSelect.call(editor.pickaday, date);
331
        }
332

333
        if (editor.hot.rootWindow.matchMedia("(pointer: coarse)").matches) {
334
          editor.hideDatepicker(editor);
335
        }
336
      };
337
      options.onClose = () => {
338
        if (!editor.parentDestroyed) {
339
          editor.finishEditing(false);
340
        }
341
        if (origOnClose) {
342
          origOnClose();
343
        }
344
      };
345

346
      return options;
347
    },
348
    hideDatepicker(editor) {
349
      editor.pickaday?.hide();
350
    },
351
    showDatepicker(editor, event) {
352
      const dateFormat = editor.getDateFormat(editor);
353
      // TODO: view is not exported in the handsontable library d.ts, so we need to use @ts-ignore
354
      // @ts-ignore
355
      const isMouseDown = editor.hot.view.isMouseDown();
356
      // A printable character reports a single-character `key`; anything else is a function key.
357
      const isMeta = event && "key" in event
358
        ? (event as KeyboardEvent).key.length > 1
359
        : false;
360
      let dateStr;
361

362
      editor.datePicker.style.display = "block";
363

364
      editor.pickaday = new Pikaday(editor.getDatePickerConfig(editor));
365

366
      // TODO: _onInputFocus is not exported in the pikaday library d.ts, so we need to use @ts-ignore
367
      // @ts-ignore
368
      editor.pickaday._onInputFocus = function () {};
369

370
      if (editor.originalValue) {
371
        dateStr = editor.originalValue;
372

373
        if (moment(dateStr, dateFormat, true).isValid()) {
374
          editor.pickaday.setDate(moment(dateStr, dateFormat).toDate(), true);
375
        }
376

377
        // workaround for date/time cells - pikaday resets the cell value to 12:00 AM by default, this will overwrite the value.
378
        if (editor.getValue() !== editor.originalValue) {
379
          editor.setValue(editor.originalValue);
380
        }
381

382
        if (!isMeta && !isMouseDown) {
383
          editor.setValue("");
384
        }
385
      } else if (editor.cellProperties.defaultDate) {
386
        dateStr = editor.cellProperties.defaultDate;
387

388
        if (moment(dateStr, dateFormat, true).isValid()) {
389
          editor.pickaday.setDate(moment(dateStr, dateFormat).toDate(), true);
390
        }
391

392
        if (!isMeta && !isMouseDown) {
393
          editor.setValue("");
394
        }
395
      } else {
396
        // if a default date is not defined, set a soft-default-date: display the current day and month in the
397
        // datepicker, but don't fill the editor input
398
        editor.pickaday.gotoToday();
399
      }
400
    },
401
    afterClose(editor) {
402
      if (editor.pickaday?.destroy) {
403
        editor.pickaday.destroy();
404
      }
405
    },
406

407
    afterOpen(editor, event) {
408
      const cellRect = editor.TD.getBoundingClientRect();
409

410
      editor.input.style.width = `${cellRect.width}px`;
411
      editor.input.style.height = `${cellRect.height}px`;
412
      editor.showDatepicker(editor, event);
413
    },
414
    getValue(editor) {
415
      return editor.input.value;
416
    },
417
    setValue(editor, value) {
418
      editor.input.value = value;
419
    },
420
    getDateFormat(
421
      editor: FactoryEditorType<EditorPropertiesType, EditorMethodsType>,
422
    ) {
423
      return editor.cellProperties.dateFormat ?? DEFAULT_DATE_FORMAT;
424
    },
425
  }),
426
};
427

428
// Define configuration options for the Handsontable
429
const hotOptions: Handsontable.GridSettings = {
430
  data,
431
  height: "auto",
432
  colHeaders: ["Item Name", "Category", "Lead Engineer", "Restock Date", "Cost"],
433
  autoRowSize: true,
434
  rowHeaders: true,
435
  width: "100%",
436
  autoWrapRow: true,
437
  headerClassName: "htLeft",
438
  columns: [
439
    { data: "itemName", type: "text", width: 130 },
440
    { data: "category", type: "text", width: 120 },
441
    { data: "leadEngineer", type: "text", width: 150 },
442
    {
443
      data: "restockDate",
444
      width: 150,
445
      allowInvalid: false,
446
      ...cellDefinition,
447
      renderFormat: DATE_FORMAT_US,
448
      dateFormat: DATE_FORMAT_US,
449
      defaultDate: "01/01/2020",
450
      datePickerConfig: {
451
        firstDay: 0,
452
        showWeekNumber: true,
453
        disableDayFn(date: Date) {
454
          return date.getDay() === 0 || date.getDay() === 6;
455
        },
456
      },
457
    },
458
    {
459
      data: "cost",
460
      type: "numeric",
461
      width: 120,
462
      className: "htRight",
463
      locale: "en-US",
464
      numericFormat: {
465
        style: "currency",
466
        currency: "USD",
467
        minimumFractionDigits: 2,
468
      },
469
    },
470
  ],
471
  licenseKey: "non-commercial-and-evaluation",
472
};
473

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

1
.ht_editor_visible > input {
2
  width: 100%;
3
  height: 100%;
4
  box-sizing: border-box !important;
5
  border: none;
6
  border-radius: 0;
7
  outline: none;
8
  margin-top: -1px;
9
  margin-left: -1px;
10
  box-shadow: inset 0 0 0 var(--ht-cell-editor-border-width, 2px)
11
    var(--ht-cell-editor-border-color, #1a42e8),
12
    0 0 var(--ht-cell-editor-shadow-blur-radius, 0) 0
13
    var(--ht-cell-editor-shadow-color, transparent) !important;
14
  background-color: var(--ht-cell-editor-background-color, #ffffff) !important;
15
  padding: var(--ht-cell-vertical-padding, 4px)
16
    var(--ht-cell-horizontal-padding, 8px) !important;
17
  border: none !important;
18
  font-family: inherit;
19
  font-size: var(--ht-font-size);
20
  line-height: var(--ht-line-height);
21
}
22
.ht_editor_visible > input:focus-visible {
23
  border: none !important;
24
  outline: none !important;
25
}
26

27
/* Pikaday's own stylesheet ships hardcoded light-mode colors. These rules re-point every
28
   visual property at Handsontable's theme variables, so the calendar follows the active
29
   theme -- including dark mode.
30

31
   Every selector is scoped to the element carrying the theme class. That element is the
32
   body-level `.ht-portal` the editor is attached to by `position: 'portal'`, so the
33
   `--ht-*` variables and the theme's `color-scheme` resolve on the calendar's own
34
   ancestor. Scoping this way also keeps each rule one class more specific than the
35
   matching rule in `pikaday.css`, which wins on source order otherwise.
36

37
   Handsontable shipped equivalent rules until 18.0, when the built-in Pikaday date editor
38
   was replaced by a native date input. The recipe now owns them. */
39
[class*='ht-theme-'] .pika-single {
40
  position: relative;
41
  display: block;
42
  z-index: 9999;
43
  padding: 10px;
44
  font-family: var(--ht-font-family), -apple-system, BlinkMacSystemFont, "Segoe UI",
45
    sans-serif;
46
  font-size: var(--ht-font-size);
47
  line-height: var(--ht-line-height);
48
  font-weight: var(--ht-font-weight);
49
  color: var(--ht-foreground-color);
50
  background: var(--ht-background-color, #ffffff);
51
  border: var(--ht-menu-border-width, 1px) solid var(--ht-menu-border-color, #e5e5e9);
52
  border-radius: var(--ht-menu-border-radius);
53
  box-shadow: var(--ht-menu-shadow-x, 0) var(--ht-menu-shadow-y, 0)
54
    var(--ht-menu-shadow-blur, 8px)
55
    color-mix(
56
      in srgb,
57
      var(--ht-menu-shadow-color, rgba(0, 0, 0)) var(--ht-menu-shadow-opacity, 100%),
58
      transparent
59
    );
60
}
61

62
[class*='ht-theme-'] .pika-single.is-hidden {
63
  display: none;
64
}
65

66
[class*='ht-theme-'] .pika-single .pika-row {
67
  background-color: transparent;
68
}
69

70
[class*='ht-theme-'] .pika-single .pika-title {
71
  display: flex;
72
  align-items: center;
73
  justify-content: center;
74
}
75

76
[class*='ht-theme-'] .pika-single .pika-label {
77
  position: relative;
78
  order: 2;
79
  padding: 5px;
80
  color: var(--ht-accent-color);
81
  background-color: transparent;
82
}
83

84
[class*='ht-theme-'] .pika-single .pika-label .pika-select {
85
  position: absolute;
86
  inset: 0;
87
  opacity: 0;
88
  cursor: pointer;
89
}
90

91
/* Replace Pikaday's baked-in PNG arrows with the theme's chevron. `currentColor` on the
92
   mask keeps them in step with the accent color in both light and dark mode. */
93
[class*='ht-theme-'] .pika-single .pika-prev,
94
[class*='ht-theme-'] .pika-single .pika-next {
95
  width: var(--ht-icon-size, 20px);
96
  height: var(--ht-icon-size, 20px);
97
  padding: 0;
98
  white-space: nowrap;
99
  text-indent: -9999px;
100
  cursor: pointer;
101
  opacity: 1;
102
  color: var(--ht-accent-color);
103
  border: none;
104
  background-image: none;
105
  background-color: currentColor;
106
  -webkit-mask-size: contain;
107
  mask-size: contain;
108
  -webkit-mask-repeat: no-repeat;
109
  mask-repeat: no-repeat;
110
  -webkit-mask-position: center;
111
  mask-position: center;
112
}
113

114
[class*='ht-theme-'] .pika-single .pika-prev.is-disabled,
115
[class*='ht-theme-'] .pika-single .pika-next.is-disabled {
116
  opacity: 0.2;
117
  cursor: default;
118
}
119

120
[class*='ht-theme-'] .pika-single .pika-next {
121
  order: 3;
122
  margin-left: auto;
123
  -webkit-mask-image: url("data:image/svg+xml;charset=utf-8,%3Csvg width='16' height='16' viewBox='0 0 16 16' fill='none' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath d='M6.64648 10.9393L9.93938 7.64644L6.64648 4.35354' stroke='currentColor' stroke-linecap='round' stroke-linejoin='round'/%3E%3C/svg%3E%0A");
124
  mask-image: url("data:image/svg+xml;charset=utf-8,%3Csvg width='16' height='16' viewBox='0 0 16 16' fill='none' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath d='M6.64648 10.9393L9.93938 7.64644L6.64648 4.35354' stroke='currentColor' stroke-linecap='round' stroke-linejoin='round'/%3E%3C/svg%3E%0A");
125
}
126

127
[class*='ht-theme-'] .pika-single .pika-prev {
128
  order: 1;
129
  margin-right: auto;
130
  -webkit-mask-image: url("data:image/svg+xml;charset=utf-8,%3Csvg width='16' height='16' viewBox='0 0 16 16' fill='none' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath d='M9.49268 11.2929L6.19978 8.00001L9.49268 4.70712' stroke='currentColor' stroke-linecap='round' stroke-linejoin='round'/%3E%3C/svg%3E%0A");
131
  mask-image: url("data:image/svg+xml;charset=utf-8,%3Csvg width='16' height='16' viewBox='0 0 16 16' fill='none' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath d='M9.49268 11.2929L6.19978 8.00001L9.49268 4.70712' stroke='currentColor' stroke-linecap='round' stroke-linejoin='round'/%3E%3C/svg%3E%0A");
132
}
133

134
.pika-single .pika-table,
135
[class*='ht-theme-'] .pika-single .pika-table {
136
  border-collapse: collapse;
137
  table-layout: fixed;
138
}
139

140
[class*='ht-theme-'] .pika-single .pika-table thead {
141
  height: 50px;
142
}
143

144
[class*='ht-theme-'] .pika-single .pika-table th {
145
  padding: 1px;
146
  vertical-align: middle;
147
  color: var(--ht-foreground-color);
148
}
149

150
[class*='ht-theme-'] .pika-single .pika-table th abbr {
151
  text-decoration: none;
152
  font-weight: normal;
153
  border: none;
154
  cursor: initial;
155
}
156

157
[class*='ht-theme-'] .pika-single .pika-table td {
158
  padding: 1px;
159
  vertical-align: middle;
160
}
161

162
.pika-single .pika-table .pika-button,
163
[class*='ht-theme-'] .pika-single .pika-table .pika-button {
164
  width: 100%;
165
  aspect-ratio: 1 / 1;
166
  box-sizing: border-box;
167
  margin: 0;
168
  padding: 0;
169
  background: transparent;
170
  color: var(--ht-foreground-color);
171
  border: none;
172
  border-radius: var(--ht-button-border-radius);
173
  box-shadow: none;
174
  cursor: pointer;
175
  font-size: inherit;
176
  text-align: center !important;
177
}
178

179
[class*='ht-theme-'] .pika-single .pika-table .pika-button:hover,
180
[class*='ht-theme-'] .pika-single .pika-table td.is-today .pika-button {
181
  color: var(--ht-foreground-color);
182
  background: color-mix(
183
    in srgb,
184
    var(--ht-menu-item-hover-color) var(--ht-menu-item-hover-color-opacity, 12%),
185
    transparent
186
  );
187
}
188

189
[class*='ht-theme-'] .pika-single .pika-table td.is-selected .pika-button,
190
[class*='ht-theme-'] .pika-single .pika-table td.is-selected .pika-button:hover {
191
  background: var(--ht-accent-color, #1a42e8);
192
  color: var(--ht-primary-button-foreground-color, #ffffff);
193
  box-shadow: none;
194
}
195

196
[class*='ht-theme-'] .pika-single .pika-table td.is-disabled .pika-button {
197
  pointer-events: none;
198
  opacity: 0.5;
199
}
200

201
[class*='ht-theme-'] .pika-single .pika-table td.is-outside-current-month .pika-button {
202
  opacity: 0.5;
203
}
204

205
[class*='ht-theme-'] .pika-single .pika-table td.pika-week {
206
  width: calc(100% / 8);
207
  text-align: center;
208
  color: var(--ht-foreground-color);
209
}
210

211
/* Right-to-left: Pikaday adds `.is-rtl` to the calendar root. */
212
[class*='ht-theme-'] .pika-single.is-rtl .pika-next {
213
  transform: rotate(180deg);
214
  margin-left: 0;
215
  margin-right: auto;
216
}
217

218
[class*='ht-theme-'] .pika-single.is-rtl .pika-prev {
219
  transform: rotate(180deg);
220
  margin-left: auto;
221
  margin-right: 0;
222
}

Overview

This guide shows how to create a custom date picker cell using Pikaday, a date picker library with no dependencies. Migration note: Handsontable 18.0 removed Pikaday from the built-in date cell type, which now uses a native date input. Use this recipe to keep Pikaday functionality in your application.

Difficulty: Intermediate Time: ~25 minutes Libraries: pikaday, moment

What You’ll Build

A cell that:

Displays formatted dates (e.g., “12/31/2024” or “31/12/2024”)
Opens a calendar picker when edited, themed to match the grid
Supports per-column configuration (date formats, first day of week, disabled dates)
Handles keyboard navigation (arrow keys to navigate dates)
Auto-closes and saves when a date is selected
Works with portal positioning for better z-index handling

Prerequisites

1
npm install pikaday moment

TypeScript users also need the community type definitions, which Pikaday does not ship itself:

1
npm install --save-dev @types/pikaday

Why these libraries?

pikaday - The Pikaday date picker library
moment - Date formatting and parsing (can be replaced with date-fns, dayjs, etc.)

Import Dependencies

1
import Handsontable from 'handsontable/base';
2
import { registerAllModules } from 'handsontable/registry';
3
import moment from 'moment';
4
import Pikaday from 'pikaday';
5
import 'pikaday/css/pikaday.css';
6
import { CellProperties } from 'handsontable/settings';
7
import { editorFactory } from 'handsontable/editors';
8
import { rendererFactory } from 'handsontable/renderers';
9

10
registerAllModules();

What we’re importing:

Handsontable core and styles
editorFactory and rendererFactory for creating custom cell type components
Pikaday for date picker functionality
pikaday/css/pikaday.css for the calendar panel structure
Moment for date formatting and parsing

Define Date Formats
```
1
const DATE_FORMAT_US = 'MM/DD/YYYY';
2
const DEFAULT_DATE_FORMAT = DATE_FORMAT_US;
```
Why constants?
- Reusability across renderer and column configuration
- Single source of truth
- Add more formats (EU, ISO, custom, etc.) by extending this list

Define TypeScript Types

Define types for editor properties and methods to ensure type safety.

1
type EditorPropertiesType = {
2
  input: HTMLInputElement;
3
  pickaday: Pikaday;
4
  datePicker: HTMLDivElement;
5
  parentDestroyed: boolean;
6
};
7

8
// Helper type to extract the editor type from factory callbacks
9
type FactoryEditorType<TProps, TMethods> = Parameters<
10
  Parameters<
11
    typeof editorFactory<TProps, TMethods>
12
  >[0]["init"]
13
>[0];
14

15
type EditorMethodsType = {
16
  showDatepicker: (
17
    editor: FactoryEditorType<EditorPropertiesType, EditorMethodsType>,
18
    event: Event | undefined,
19
  ) => void;
20
  hideDatepicker: (
21
    editor: FactoryEditorType<EditorPropertiesType, EditorMethodsType>,
22
  ) => void;
23
  getDatePickerConfig: (
24
    editor: FactoryEditorType<EditorPropertiesType, EditorMethodsType>,
25
  ) => Pikaday.PikadayOptions;
26
  getDateFormat: (
27
    editor: FactoryEditorType<EditorPropertiesType, EditorMethodsType>,
28
  ) => string;
29
};

What’s happening:

EditorPropertiesType: Defines custom properties added to the editor instance
FactoryEditorType: Helper to extract the correct editor type from factory callbacks
EditorMethodsType: Defines custom methods that will be available on the editor

Why this matters:

Provides full TypeScript type safety
Enables autocomplete in your IDE
Catches type errors at compile time

Create the Renderer

The renderer controls how the cell looks when not being edited.
```
1
renderer: rendererFactory(({ td, value, cellProperties }) => {
2
  td.innerText = moment(new Date(value), cellProperties.renderFormat).format(
3
    cellProperties.renderFormat,
4
  );
5
})
```
What’s happening:
- value is the raw date value (e.g., ISO string “2024-12-31” or formatted “12/31/2024”)
- cellProperties.renderFormat is a custom property we’ll set per column
- moment().format() converts to desired format
- Display the formatted date
Why use cellProperties?
- Allows different columns to display dates differently
- One cell definition, multiple configurations

Editor - Initialize (`init`)

Create the input element and set up event handling to prevent clicks on the datepicker from closing the editor.

1
init(editor) {
2
  editor.parentDestroyed = false;
3
  // Create the input element on init. This is a text input that date picker will be attached to.
4
  editor.input = editor.hot.rootDocument.createElement(
5
    'input',
6
  ) as HTMLInputElement;
7

8
  // Use the container as the date picker container
9
  editor.datePicker = editor.container;
10

11
  /**
12
   * Prevent recognizing clicking on datepicker as clicking outside of table.
13
   */
14
  editor.hot.rootDocument.addEventListener('mousedown', (event) => {
15
      if (
16
        event.target &&
17
        (event.target as HTMLElement).classList.contains('pika-day')
18
      ) {
19
        editor.hideDatepicker(editor);
20
      }
21
    },
22
  );
23
}

What’s happening:

Initialize parentDestroyed flag to track editor lifecycle
Create an input element using editor.hot.rootDocument.createElement()
Use the editor container as the Pikaday container
Create event listener to handle clicks on datepicker days
The editorFactory helper handles container creation and DOM insertion

Key concepts:

The `Event Listener` pattern

This is crucial! Without it:

User clicks cell to edit
Pikaday calendar opens
User clicks on a calendar day
Handsontable thinks user clicked “outside” the editor
Editor closes immediately!

Solution:

1
editor.hot.rootDocument.addEventListener('mousedown', (event) => {
2
  if ((event.target as HTMLElement).classList.contains('pika-day')) {
3
    editor.hideDatepicker(editor);
4
  }
5
});

Why `editor.hot.rootDocument.createElement()`?

Handsontable might be in an iframe or shadow DOM
editor.hot.rootDocument ensures correct document context
Ensures compatibility across different environments

Editor - Get Date Picker Config (`getDatePickerConfig`)

Build the Pikaday configuration object with proper callbacks.

1
getDatePickerConfig(editor) {
2
  const htInput = editor.input;
3
  const options: Pikaday.PikadayOptions = {};
4

5
  // Merge custom config from cell properties
6
  if (editor.cellProperties && editor.cellProperties.datePickerConfig) {
7
    Object.assign(options, editor.cellProperties.datePickerConfig);
8
  }
9
  const origOnSelect = options.onSelect;
10
  const origOnClose = options.onClose;
11

12
  // Configure Pikaday
13
  options.field = htInput;
14
  options.trigger = htInput;
15
  options.container = editor.datePicker;
16
  options.bound = false;
17
  options.keyboardInput = false;
18
  options.format = options.format ?? editor.getDateFormat(editor);
19
  options.toString = (date, format) => moment(date).format(format);
20
  options.parse = (dateString, format) => moment(dateString, format).toDate();
21
  options.reposition = options.reposition || false;
22
  options.isRTL = false;
23

24
  // Handle date selection
25
  options.onSelect = function (date) {
26
    let dateStr;
27

28
    if (!isNaN(date.getTime())) {
29
      dateStr = moment(date).format(editor.getDateFormat(editor));
30
    }
31
    editor.setValue(dateStr);
32

33
    if (origOnSelect) {
34
      origOnSelect.call(editor.pickaday, date);
35
    }
36

37
    if (editor.hot.rootWindow.matchMedia('(pointer: coarse)').matches) {
38
      editor.hideDatepicker(editor);
39
    }
40
  };
41

42
  // Handle date picker close
43
  options.onClose = () => {
44
    if (!editor.parentDestroyed) {
45
      editor.finishEditing(false);
46
    }
47
    if (origOnClose) {
48
      origOnClose();
49
    }
50
  };
51

52
  return options;
53
}

What’s happening:

Start with empty options object
Merge custom config from cellProperties.datePickerConfig (allows per-column customization)
Store original callbacks to preserve them
Configure Pikaday with editor-specific settings
Set up onSelect to format date and save value
Set up onClose to finish editing

Key configuration options:

field: The input element Pikaday attaches to
trigger: Element that triggers the picker (same as field)
container: Where to render the calendar (editor container)
bound: false: Don’t position relative to field
keyboardInput: false: Disable direct keyboard input (handled via shortcuts)
reposition: false: Don’t auto-reposition (positioning is handled manually)
toString and parse: Route display formatting and input parsing through Moment.js

Pikaday formats and parses dates with Moment.js only when it can reach moment itself, which it cannot under a bundler. Without these two hooks it falls back to Date#toDateString() on display and Date.parse() on input, so format is ignored and a DD/MM/YYYY column misreads its own values. Pikaday checks toString and parse before its internal path, so setting them makes format authoritative in both directions.

Editor - Show Datepicker (`showDatepicker`)

Initialize and display the Pikaday calendar when the editor opens.

1
showDatepicker(editor, event) {
2
  const dateFormat = editor.getDateFormat(editor);
3
  // @ts-ignore
4
  const isMouseDown = editor.hot.view.isMouseDown();
5
  // A printable character reports a single-character `key`; anything else is a function key.
6
  const isMeta = event && 'key' in event
7
    ? (event as KeyboardEvent).key.length > 1
8
    : false;
9
  let dateStr;
10

11
  editor.datePicker.style.display = 'block';
12

13
  // Create new Pikaday instance
14
  editor.pickaday = new Pikaday(editor.getDatePickerConfig(editor));
15

16
  // @ts-ignore
17
  editor.pickaday._onInputFocus = function () {};
18

19
  // Handle existing value
20
  if (editor.originalValue) {
21
    dateStr = editor.originalValue;
22

23
    if (moment(dateStr, dateFormat, true).isValid()) {
24
      editor.pickaday.setDate(moment(dateStr, dateFormat).toDate(), true);
25
    }
26

27
    if (editor.getValue() !== editor.originalValue) {
28
      editor.setValue(editor.originalValue);
29
    }
30

31
    if (!isMeta && !isMouseDown) {
32
      editor.setValue('');
33
    }
34
  } else if (editor.cellProperties.defaultDate) {
35
    dateStr = editor.cellProperties.defaultDate;
36

37
    if (moment(dateStr, dateFormat, true).isValid()) {
38
      editor.pickaday.setDate(moment(dateStr, dateFormat).toDate(), true);
39
    }
40

41
    if (!isMeta && !isMouseDown) {
42
      editor.setValue('');
43
    }
44
  } else {
45
    editor.pickaday.gotoToday();
46
  }
47
}

What’s happening:

Get date format for parsing
Check if mouse is down or function key pressed (for special behavior)
Show the date picker container
Create new Pikaday instance with configuration
Disable input focus handler (focus is handled by the editor lifecycle)
Set initial date based on cell value, default date, or today

Key concepts:

Why create Pikaday instance in `showDatepicker`?

Pikaday instance is created fresh each time editor opens
Allows per-edit configuration changes
Ensures clean state for each edit session

The `isMeta` and `isMouseDown` checks

If function key (F2, etc.) or mouse is down, don’t clear the input
Preserves value when opening via keyboard or programmatically
Provides better UX for keyboard users

Editor - Hide Datepicker (hideDatepicker)

Close the Pikaday calendar.
```
1
hideDatepicker(editor) {
2
  editor.pickaday?.hide();
3
}
```
Editor - After Open Hook (afterOpen)

Match the editor input dimensions to the cell and show the datepicker.
```
1
afterOpen(editor, event) {
2
  const cellRect = editor.TD.getBoundingClientRect();
3

4
  editor.input.style.width = `${cellRect.width}px`;
5
  editor.input.style.height = `${cellRect.height}px`;
6
  editor.showDatepicker(editor, event);
7
}
```
What’s happening:
1. Get the cell’s bounding rectangle for exact dimensions
2. Set the input width and height to match the cell
3. Show the datepicker
Why getBoundingClientRect?
- Provides pixel-perfect dimensions matching the cell
- Works correctly regardless of cell padding, borders, or theme
- The CSS file handles the visual styling (borders, padding, focus states)
Editor - After Close Hook (afterClose)

Clean up the Pikaday instance when the editor closes.
```
1
afterClose(editor) {
2
  if (editor.pickaday?.destroy) {
3
    editor.pickaday.destroy();
4
  }
5
}
```
Why this matters:
- Pikaday creates DOM elements and event listeners
- Without cleanup, these accumulate over time
- Essential for long-running applications
- The instance check is required: Handsontable can close an editor that never opened (for example, when the edited cell leaves the rendered viewport), so pickaday may not exist yet
Editor - Get Value and Set Value

Standard value management methods.
```
1
getValue(editor) {
2
  return editor.input.value;
3
}
4

5
setValue(editor, value) {
6
  editor.input.value = value;
7
}
```
- Pikaday automatically updates input.value when a date is selected
- getValue and setValue read and write the input value directly
- Formatting is handled by Pikaday and the onSelect callback

Editor - Get Date Format (`getDateFormat`)

Helper method to get the date format for the current cell.

1
getDateFormat(
2
  editor: FactoryEditorType<EditorPropertiesType, EditorMethodsType>,
3
) {
4
  return editor.cellProperties.dateFormat ?? DEFAULT_DATE_FORMAT;
5
}

Editor - Keyboard Shortcuts

Add keyboard navigation for date selection.

1
shortcuts: [
2
  {
3
    keys: [['ArrowLeft']],
4
    callback: (editor, _event) => {
5
      editor.pickaday.adjustDate('subtract', 1);
6
      _event.preventDefault();
7
    },
8
  },
9
  {
10
    keys: [['ArrowRight']],
11
    callback: (editor, _event) => {
12
      editor.pickaday.adjustDate('add', 1);
13
      _event.preventDefault();
14
    },
15
  },
16
  {
17
    keys: [['ArrowUp']],
18
    callback: (editor, _event) => {
19
      editor.pickaday.adjustDate('subtract', 7);
20
      _event.preventDefault();
21
    },
22
  },
23
  {
24
    keys: [['ArrowDown']],
25
    callback: (editor, _event) => {
26
      editor.pickaday.adjustDate('add', 7);
27
      _event.preventDefault();
28
    },
29
  }
30
]

What’s happening:

ArrowLeft: Move back one day
ArrowRight: Move forward one day
ArrowUp: Move back one week (7 days)
ArrowDown: Move forward one week (7 days)

Editor - Portal Positioning

Use portal positioning for better z-index handling.
```
1
position: 'portal',
```
Why portal instead of container?
- Datepicker can extend beyond cell boundaries
- Portal ensures it’s always on top
- Better for complex layouts

Editor Input and Calendar Styling (CSS)

Two stylesheets are involved. Style the editor input to match Handsontable’s native editor appearance using CSS custom properties, then re-point the calendar’s own colors at the same theme variables.

1
.ht_editor_visible > input {
2
  width: 100%;
3
  height: 100%;
4
  box-sizing: border-box !important;
5
  border: none;
6
  border-radius: 0;
7
  outline: none;
8
  margin-top: -1px;
9
  margin-left: -1px;
10
  box-shadow: inset 0 0 0 var(--ht-cell-editor-border-width, 2px)
11
    var(--ht-cell-editor-border-color, #1a42e8),
12
    0 0 var(--ht-cell-editor-shadow-blur-radius, 0) 0
13
    var(--ht-cell-editor-shadow-color, transparent) !important;
14
  background-color: var(--ht-cell-editor-background-color, #ffffff) !important;
15
  padding: var(--ht-cell-vertical-padding, 4px)
16
    var(--ht-cell-horizontal-padding, 8px) !important;
17
  border: none !important;
18
  font-family: inherit;
19
  font-size: var(--ht-font-size);
20
  line-height: var(--ht-line-height);
21
}
22
.ht_editor_visible > input:focus-visible {
23
  border: none !important;
24
  outline: none !important;
25
}

What’s happening:

Uses Handsontable’s CSS custom properties (--ht-cell-editor-*) for theme compatibility
inset box-shadow replaces borders for the blue editor highlight
-1px margins correct portal positioning offset
Inherits font properties from the table for consistency
:focus-visible overrides prevent browser default focus styles

Theming the calendar

pikaday/css/pikaday.css gives the calendar its layout, but every color in it is a hardcoded literal, and its prev/next arrows are baked-in PNG sprites. On a Handsontable theme the panel clashes, and on a dark page it stays light. Override those properties with the theme’s CSS variables:

1
.pika-single {
2
  color: var(--ht-foreground-color);
3
  background: var(--ht-background-color, #ffffff);
4
  border: var(--ht-menu-border-width, 1px) solid var(--ht-menu-border-color, #e5e5e9);
5
  border-radius: var(--ht-menu-border-radius);
6
}
7

8
.pika-single .pika-table .pika-button {
9
  width: 100%;
10
  aspect-ratio: 1 / 1;
11
  box-sizing: border-box;
12
  margin: 0;
13
  padding: 0;
14
  background: transparent;
15
  color: var(--ht-foreground-color);
16
  border-radius: var(--ht-button-border-radius);
17
  text-align: center !important;
18
}
19

20
.pika-single .pika-table {
21
  border-collapse: collapse;
22
  table-layout: fixed;
23
}
24

25
.pika-single .pika-table td.is-selected .pika-button {
26
  background: var(--ht-accent-color, #1a42e8);
27
  color: var(--ht-primary-button-foreground-color, #ffffff);
28
}

table-layout: fixed gives the calendar equal-width day columns, including when week numbers are enabled. box-sizing: border-box and zero padding keep one- and two-digit day labels centered in their buttons.

The full rule set is in the CSS tab of the example above, including the arrow replacement and the right-to-left flip.

Why this works without extra wiring: the editor uses position: 'portal', so its container is attached to the body-level .ht-portal element, and Handsontable puts the active ht-theme-* class on that element. Every --ht-* variable and the theme’s color-scheme resolve on the calendar’s own ancestor, so the panel follows the grid’s theme — light or dark — with no JavaScript.

Handsontable shipped equivalent rules until 18.0, when the native date input replaced the built-in Pikaday editor. They now belong to your application.

Complete Cell Definition

Put it all together:

1
const cellDefinition: Pick<
2
  CellProperties,
3
  'renderer' | 'validator' | 'editor'
4
> = {
5
  renderer: rendererFactory(({ td, value, cellProperties }) => {
6
    td.innerText = moment(new Date(value), cellProperties.renderFormat).format(
7
      cellProperties.renderFormat,
8
    );
9
  }),
10

11
  editor: editorFactory<
12
    EditorPropertiesType,
13
    EditorMethodsType
14
  >({
15
    position: 'portal',
16
    shortcuts: [
17
      // ... keyboard shortcuts from Step 13
18
    ],
19
    init(editor) {
20
      // ... from Step 5
21
    },
22
    getDatePickerConfig(editor) {
23
      // ... from Step 6
24
    },
25
    hideDatepicker(editor) {
26
      // ... from Step 8
27
    },
28
    showDatepicker(editor, event) {
29
      // ... from Step 7
30
    },
31
    afterClose(editor) {
32
      // ... from Step 10
33
    },
34
    afterOpen(editor, event) {
35
      // ... from Step 9
36
    },
37
    getValue(editor) {
38
      // ... from Step 11
39
    },
40
    setValue(editor, value) {
41
      // ... from Step 11
42
    },
43
    getDateFormat(editor) {
44
      // ... from Step 12
45
    },
46
  }),
47
};

Use in Handsontable

1
const container = document.querySelector('#example1')!;
2

3
const hotOptions: Handsontable.GridSettings = {
4
  data,
5
  colHeaders: ['Item Name', 'Category', 'Lead Engineer', 'Restock Date', '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: 'restockDate',
18
      width: 150,
19
      allowInvalid: false,
20
      ...cellDefinition,
21
      renderFormat: DATE_FORMAT_US,
22
      dateFormat: DATE_FORMAT_US,
23
      defaultDate: '01/01/2020',
24
      datePickerConfig: {
25
        firstDay: 0,
26
        showWeekNumber: true,
27
        disableDayFn(date: Date) {
28
          return date.getDay() === 0 || date.getDay() === 6;
29
        },
30
      },
31
    },
32
    {
33
      data: 'cost',
34
      type: 'numeric',
35
      width: 120,
36
      className: 'htRight',
37
      locale: 'en-US',
38
      numericFormat: {
39
        style: 'currency',
40
        currency: 'USD',
41
        minimumFractionDigits: 2,
42
      },
43
    },
44
  ],
45
  licenseKey: 'non-commercial-and-evaluation',
46
};
47

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

Key configuration:

...cellDefinition - Spreads renderer and editor into the column config
renderFormat - Format for displaying dates in cells
dateFormat - Format for Pikaday date picker
datePickerConfig - Additional Pikaday configuration options
defaultDate - Default date when cell is empty
headerClassName: 'htLeft' - Left-aligns all column headers

How It Works - Complete Flow

Initial Load: Cell displays formatted date (e.g., “08/01/2025”)
User Double-Clicks or F2: Editor opens, container positioned in portal
After Open: Input sized to match cell via getBoundingClientRect, showDatepicker called
Show Datepicker: Pikaday instance created, calendar displayed
User Selects Date: onSelect callback fires, formats date, saves value
User Clicks Day: Event listener detects click, hides datepicker, finishes editing
After Close: Pikaday instance destroyed, memory cleaned up
Re-render: Cell displays updated formatted date

Migration from Built-in Date Cell Type

If you’re currently using the built-in date cell type with Pikaday, here’s how to migrate:

Before (Built-in):

1
columns: [{
2
  data: 'restockDate',
3
  type: 'date',
4
  dateFormat: 'MM/DD/YYYY',
5
  datePickerConfig: {
6
    firstDay: 0,
7
  }
8
}]

After (Custom Editor):

1
columns: [{
2
  data: 'restockDate',
3
  ...cellDefinition,  // Add the custom cell definition
4
  dateFormat: 'MM/DD/YYYY',
5
  renderFormat: 'MM/DD/YYYY',  // Add render format
6
  datePickerConfig: {
7
    firstDay: 0,
8
  }
9
}]

Key differences:

Replace type: "date" with ...cellDefinition
Add renderFormat property (for cell display)
Keep dateFormat and datePickerConfig (they work the same)

Enhancements

Different Date Formats per Column

1
columns: [
2
  {
3
    data: 'restockDate',
4
    ...cellDefinition,
5
    renderFormat: 'MM/DD/YYYY',  // US format
6
    dateFormat: 'MM/DD/YYYY',
7
  },
8
  {
9
    data: 'restockDate',
10
    ...cellDefinition,
11
    renderFormat: 'DD/MM/YYYY',  // EU format
12
    dateFormat: 'DD/MM/YYYY',
13
  }
14
]

Date Range Restrictions

1
datePickerConfig: {
2
  minDate: new Date('2024-01-01'),
3
  maxDate: new Date('2024-12-31'),
4
  disableDayFn(date) {
5
    // Disable weekends
6
    return date.getDay() === 0 || date.getDay() === 6;
7
  }
8
}

Custom Date Formatting

Replace Moment.js with another library:

1
import { format, parse } from 'date-fns';
2

3
// In renderer
4
renderer: rendererFactory(({ td, value, cellProperties }) => {
5
  td.innerText = format(new Date(value), cellProperties.renderFormat);
6
})
7

8
// In getDatePickerConfig
9
options.format = 'MM/DD/YYYY'; // Pikaday format string

Localization

1
import 'pikaday/css/pikaday.css';
2
import moment from 'moment';
3
import 'moment/locale/fr';
4

5
moment.locale('fr');
6

7
datePickerConfig: {
8
  i18n: {
9
    previousMonth: 'Mois précédent',
10
    nextMonth: 'Mois suivant',
11
    months: ['Janvier', 'Février', 'Mars', ...],
12
    weekdays: ['Dimanche', 'Lundi', 'Mardi', ...],
13
    weekdaysShort: ['Dim', 'Lun', 'Mar', ...]
14
  }
15
}

Accessibility

Pikaday has good keyboard support out of the box:

Keyboard navigation:

Arrow Keys: Navigate dates (via the registered shortcuts)
Enter: Select current date
Escape: Close datepicker
Tab: Navigate to next field
Page Up/Down: Navigate months
Home/End: Navigate to first/last day of month

Screen readers: Pikaday carries some ARIA attributes of its own, but the last audit found that the built-in date cell type’s picker, which used the same library at the time, was not announced properly by screen readers. Expect the same gap in a custom Pikaday editor until you verify it. The accessibility conformance report lists it under Known open issues (WCAG 4.1.2). Test the picker with VoiceOver (macOS and iOS) and NVDA (Windows) before you rely on it.

Performance Considerations

Why This Is Fast

Lazy Initialization: Pikaday instance created only when editor opens
Efficient Cleanup: Instance destroyed when editor closes
Portal Positioning: Better z-index handling without performance cost

What you learned

You integrated the Pikaday date picker as a Handsontable cell editor. You used editorFactory with position: 'portal' for correct z-index handling, Moment.js for date formatting and parsing, and cellProperties.datePickerConfig to drive per-column Pikaday configuration.

Next steps

Moment.js date - A date cell type combining Moment.js and Pikaday in a registered moment-date cell type.
Flatpickr - An alternative date picker using the Flatpickr library.
Date picker (Angular) - A date editor built with Angular components and the native HTML5 date input.

Pikaday

Overview

What You’ll Build

Prerequisites

Import Dependencies

Define Date Formats

Define TypeScript Types

Create the Renderer

Editor - Initialize (`init`)

The `Event Listener` pattern

Why `editor.hot.rootDocument.createElement()`?

Editor - Get Date Picker Config (`getDatePickerConfig`)

Editor - Show Datepicker (`showDatepicker`)

Why create Pikaday instance in `showDatepicker`?

The `isMeta` and `isMouseDown` checks

Editor - Hide Datepicker (`hideDatepicker`)

Editor - After Open Hook (`afterOpen`)

Editor - After Close Hook (`afterClose`)

Editor - Get Value and Set Value

Editor - Get Date Format (`getDateFormat`)

Editor - Keyboard Shortcuts

Editor - Portal Positioning

Editor Input and Calendar Styling (CSS)

Theming the calendar

Complete Cell Definition

Use in Handsontable

How It Works - Complete Flow

Migration from Built-in Date Cell Type

Before (Built-in):

After (Custom Editor):

Enhancements

Different Date Formats per Column

Date Range Restrictions

Custom Date Formatting

Localization

Accessibility

Performance Considerations

Why This Is Fast

What you learned

Next steps

Pikaday

Overview

What You’ll Build

Prerequisites

Import Dependencies

Define Date Formats

Define TypeScript Types

Create the Renderer

Editor - Initialize (init)

The Event Listener pattern

Why editor.hot.rootDocument.createElement()?

Editor - Get Date Picker Config (getDatePickerConfig)

Editor - Show Datepicker (showDatepicker)

Why create Pikaday instance in showDatepicker?

The isMeta and isMouseDown checks

Editor - Hide Datepicker (hideDatepicker)

Editor - After Open Hook (afterOpen)

Editor - After Close Hook (afterClose)

Editor - Get Value and Set Value

Editor - Get Date Format (getDateFormat)

Editor - Keyboard Shortcuts

Editor - Portal Positioning

Editor Input and Calendar Styling (CSS)

Theming the calendar

Complete Cell Definition

Use in Handsontable

How It Works - Complete Flow

Migration from Built-in Date Cell Type

Before (Built-in):

After (Custom Editor):

Enhancements

Different Date Formats per Column

Date Range Restrictions

Custom Date Formatting

Localization

Accessibility

Performance Considerations

Why This Is Fast

What you learned

Next steps

Editor - Initialize (`init`)

The `Event Listener` pattern

Why `editor.hot.rootDocument.createElement()`?

Editor - Get Date Picker Config (`getDatePickerConfig`)

Editor - Show Datepicker (`showDatepicker`)

Why create Pikaday instance in `showDatepicker`?

The `isMeta` and `isMouseDown` checks

Editor - Hide Datepicker (`hideDatepicker`)

Editor - After Open Hook (`afterOpen`)

Editor - After Close Hook (`afterClose`)

Editor - Get Date Format (`getDateFormat`)