Date cell type

Display, format, sort, and filter dates correctly by using the date cell type.

Overview

The date cell type lets you treat cell values as dates: format how they are displayed, validate input, and use an interactive date picker in the editor. Handsontable supports two configurations: the object-style configuration using the native Intl.DateTimeFormat API (recommended), and a string-style configuration using Moment.js (deprecated).

Date cell type demo

In the following demo, multiple columns use the date cell type with different formatting styles:

Product date: Date with short style formatting
Payment date: Customized date formatting
Registration date: Customized date formatting with weekday, month, day, year

1
import Handsontable from 'handsontable/base';
2
import { registerAllModules } from 'handsontable/registry';
3

4
// Register all Handsontable's modules.
5
registerAllModules();
6

7
const container = document.querySelector('#example1');
8
const dropdown = document.querySelector('#localeDropdown');
9
const trigger = document.querySelector('#localeTrigger');
10
const menu = document.querySelector('#localeMenu');
11
const label = document.querySelector('#localeLabel');
32 collapsed lines
12
const data = [
13
  {
14
    car: 'Mercedes A 160',
15
    product_date: '2002-06-15',
16
    payment_date: '2002-05-20',
17
    registration_date: '2002-07-01',
18
  },
19
  {
20
    car: 'Citroën C4 Coupe',
21
    product_date: '2007-03-22',
22
    payment_date: '2007-02-28',
23
    registration_date: '2007-04-10',
24
  },
25
  {
26
    car: 'Audi A4 Avant',
27
    product_date: '2011-09-08',
28
    payment_date: '2011-08-15',
29
    registration_date: '2011-09-20',
30
  },
31
  {
32
    car: 'Opel Astra',
33
    product_date: '2012-01-30',
34
    payment_date: '2012-01-10',
35
    registration_date: '2012-02-14',
36
  },
37
  {
38
    car: 'BMW 320i Coupe',
39
    product_date: '2004-11-12',
40
    payment_date: '2004-10-20',
41
    registration_date: '2004-12-01',
42
  },
43
];
44

45
const hot = new Handsontable(container, {
46
  data,
47
  colHeaders: ['Car', 'Product date', 'Payment date', 'Registration date'],
32 collapsed lines
48
  columns: [
49
    {
50
      type: 'text',
51
      data: 'car',
52
    },
53
    {
54
      type: 'intl-date',
55
      data: 'product_date',
56
      dateFormat: {
57
        dateStyle: 'short',
58
      },
59
    },
60
    {
61
      type: 'intl-date',
62
      data: 'payment_date',
63
      dateFormat: {
64
        month: 'long',
65
        day: 'numeric',
66
        year: 'numeric',
67
      },
68
    },
69
    {
70
      type: 'intl-date',
71
      data: 'registration_date',
72
      dateFormat: {
73
        weekday: 'long',
74
        year: 'numeric',
75
        month: 'long',
76
        day: 'numeric',
77
      },
78
    },
79
  ],
80
  columnSorting: true,
81
  filters: true,
82
  dropdownMenu: true,
83
  height: 'auto',
84
  licenseKey: 'non-commercial-and-evaluation',
85
  autoWrapRow: true,
86
  autoWrapCol: true,
87
});
88

89
// Handle dropdown toggle
90
trigger.addEventListener('click', () => {
91
  const isOpen = !menu.hidden;
92

93
  menu.hidden = isOpen;
94
  trigger.setAttribute('aria-expanded', String(!isOpen));
95
});
96

97
// Handle locale selection
98
menu.addEventListener('click', (e) => {
99
  const item = e.target.closest('li[data-value]');
100

101
  if (item) {
102
    label.textContent = item.textContent.trim();
103
    menu.querySelectorAll('li').forEach((li) => li.setAttribute('aria-selected', 'false'));
104
    item.setAttribute('aria-selected', 'true');
105
    menu.hidden = true;
106
    trigger.setAttribute('aria-expanded', 'false');
107
    hot.updateSettings({ locale: item.dataset.value });
108
  }
109
});
110

111
// Close dropdown when clicking outside
112
document.addEventListener('click', (e) => {
113
  if (!dropdown.contains(e.target)) {
114
    menu.hidden = true;
115
    trigger.setAttribute('aria-expanded', 'false');
116
  }
117
});
118

119
// Close dropdown on Escape key
120
document.addEventListener('keydown', (e) => {
121
  if (e.key === 'Escape' && !menu.hidden) {
122
    menu.hidden = true;
123
    trigger.setAttribute('aria-expanded', 'false');
124
    trigger.focus();
125
  }
126
});

1
import Handsontable from 'handsontable/base';
2
import { registerAllModules } from 'handsontable/registry';
3

4
// Register all Handsontable's modules.
5
registerAllModules();
6

7
const container = document.querySelector('#example1')!;
8
const dropdown = document.querySelector('#localeDropdown')!;
9
const trigger = document.querySelector('#localeTrigger')!;
10
const menu = document.querySelector('#localeMenu')!;
11
const label = document.querySelector('#localeLabel')!;
32 collapsed lines
12
const data = [
13
  {
14
    car: 'Mercedes A 160',
15
    product_date: '2002-06-15',
16
    payment_date: '2002-05-20',
17
    registration_date: '2002-07-01',
18
  },
19
  {
20
    car: 'Citroën C4 Coupe',
21
    product_date: '2007-03-22',
22
    payment_date: '2007-02-28',
23
    registration_date: '2007-04-10',
24
  },
25
  {
26
    car: 'Audi A4 Avant',
27
    product_date: '2011-09-08',
28
    payment_date: '2011-08-15',
29
    registration_date: '2011-09-20',
30
  },
31
  {
32
    car: 'Opel Astra',
33
    product_date: '2012-01-30',
34
    payment_date: '2012-01-10',
35
    registration_date: '2012-02-14',
36
  },
37
  {
38
    car: 'BMW 320i Coupe',
39
    product_date: '2004-11-12',
40
    payment_date: '2004-10-20',
41
    registration_date: '2004-12-01',
42
  },
43
];
44

45
const hot = new Handsontable(container, {
46
  data,
47
  colHeaders: ['Car', 'Product date', 'Payment date', 'Registration date'],
32 collapsed lines
48
  columns: [
49
    {
50
      type: 'text',
51
      data: 'car',
52
    },
53
    {
54
      type: 'intl-date',
55
      data: 'product_date',
56
      dateFormat: {
57
        dateStyle: 'short',
58
      },
59
    },
60
    {
61
      type: 'intl-date',
62
      data: 'payment_date',
63
      dateFormat: {
64
        month: 'long',
65
        day: 'numeric',
66
        year: 'numeric',
67
      },
68
    },
69
    {
70
      type: 'intl-date',
71
      data: 'registration_date',
72
      dateFormat: {
73
        weekday: 'long',
74
        year: 'numeric',
75
        month: 'long',
76
        day: 'numeric',
77
      },
78
    },
79
  ],
80
  columnSorting: true,
81
  filters: true,
82
  dropdownMenu: true,
83
  height: 'auto',
84
  licenseKey: 'non-commercial-and-evaluation',
85
  autoWrapRow: true,
86
  autoWrapCol: true,
87
});
88

89
// Handle dropdown toggle
90
trigger.addEventListener('click', () => {
91
  const isOpen = !menu.hidden;
92

93
  menu.hidden = isOpen;
94
  trigger.setAttribute('aria-expanded', String(!isOpen));
95
});
96

97
// Handle locale selection
98
menu.addEventListener('click', (e) => {
99
  const item = (e.target as HTMLElement).closest('li[data-value]') as HTMLLIElement | null;
100

101
  if (item) {
102
    label.textContent = item.textContent!.trim();
103
    menu.querySelectorAll('li').forEach((li) => li.setAttribute('aria-selected', 'false'));
104
    item.setAttribute('aria-selected', 'true');
105
    menu.hidden = true;
106
    trigger.setAttribute('aria-expanded', 'false');
107
    hot.updateSettings({ locale: item.dataset.value });
108
  }
109
});
110

111
// Close dropdown when clicking outside
112
document.addEventListener('click', (e) => {
113
  if (!dropdown.contains(e.target as Node)) {
114
    menu.hidden = true;
115
    trigger.setAttribute('aria-expanded', 'false');
116
  }
117
});
118

119
// Close dropdown on Escape key
120
document.addEventListener('keydown', (e) => {
121
  if (e.key === 'Escape' && !menu.hidden) {
122
    menu.hidden = true;
123
    trigger.setAttribute('aria-expanded', 'false');
124
    trigger.focus();
125
  }
126
});

1
<div class="example-controls-container">
2
  <div class="controls">
3
    <div class="theme-dropdown" id="localeDropdown">
4
      <button class="theme-dropdown-trigger" id="localeTrigger" type="button" aria-haspopup="listbox" aria-expanded="false">
5
        <span id="localeLabel">English (United States)</span>
6
        <svg class="theme-dropdown-chevron" aria-hidden="true" width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M6 9l6 6l6 -6"/></svg>
7
      </button>
8
      <ul class="theme-dropdown-menu" id="localeMenu" role="listbox" hidden>
9
        <li role="option" data-value="ar-AR">Arabic (Global)</li>
10
        <li role="option" data-value="cs-CZ">Czech (Czechia)</li>
11
        <li role="option" data-value="de-CH">German (Switzerland)</li>
12
        <li role="option" data-value="de-DE">German (Germany)</li>
13
        <li role="option" data-value="en-US" aria-selected="true">English (United States)</li>
14
        <li role="option" data-value="es-MX">Spanish (Mexico)</li>
15
        <li role="option" data-value="fa-IR">Persian (Iran)</li>
16
        <li role="option" data-value="fr-FR">French (France)</li>
17
        <li role="option" data-value="hr-HR">Croatian (Croatia)</li>
18
        <li role="option" data-value="it-IT">Italian (Italy)</li>
19
        <li role="option" data-value="ja-JP">Japanese (Japan)</li>
20
        <li role="option" data-value="ko-KR">Korean (Korea)</li>
21
        <li role="option" data-value="lv-LV">Latvian (Latvia)</li>
22
        <li role="option" data-value="nb-NO">Norwegian Bokmal (Norway)</li>
23
        <li role="option" data-value="nl-NL">Dutch (Netherlands)</li>
24
        <li role="option" data-value="pl-PL">Polish (Poland)</li>
25
        <li role="option" data-value="pt-BR">Portuguese (Brazil)</li>
26
        <li role="option" data-value="ru-RU">Russian (Russia)</li>
27
        <li role="option" data-value="sr-SP">Serbian Latin (Serbia)</li>
28
        <li role="option" data-value="zh-CN">Chinese (Simplified, China)</li>
29
        <li role="option" data-value="zh-TW">Chinese (Traditional, Taiwan)</li>
30
      </ul>
31
    </div>
32
  </div>
33
</div>
34

35
<div id="example1"></div>

Use the date cell type

Use the object-style configuration by setting the type option to 'intl-date' and dateFormat to an object (recommended). The locale is controlled via the locale option.

1
// set the date cell type for the entire grid (Intl, recommended)
2
type: 'intl-date',
3
locale: 'en-US',
4
dateFormat: {
5
  year: 'numeric',
6
  month: '2-digit',
7
  day: '2-digit'
8
},
9

10
// set the date cell type for a single column
11
columns: [
12
  {
13
    type: 'intl-date',
14
    locale: 'en-US',
15
    dateFormat: {
16
      dateStyle: 'short'
17
    }
18
  }
19
],
20

21
// set the date cell type for a single cell
22
cell: [
23
  {
24
    row: 0,
25
    col: 2,
26
    type: 'intl-date',
27
    locale: 'en-US',
28
    dateFormat: { dateStyle: 'medium' }
29
  }
30
],

For intl-date cells, source data must be in ISO 8601 date format (YYYY-MM-DD) for dates to work correctly. The dateFormat object only affects how dates are displayed; sorting and filtering rely on the underlying ISO value.

Format dates

To control how dates are displayed in cell renderers, use the dateFormat option.

Since Handsontable 17.0, the recommended approach is the object form of dateFormat with the intl-date cell type, which uses the native Intl.DateTimeFormat API. The locale is controlled separately via the locale option.

Using Intl.DateTimeFormat (recommended)

The dateFormat option accepts all properties of Intl.DateTimeFormat options. Use it with type: 'intl-date'.

1
columns: [
2
  {
3
    type: 'intl-date',
4
    locale: 'en-US',
5
    dateFormat: {
6
      year: 'numeric',
7
      month: '2-digit',
8
      day: '2-digit'
9
    }
10
  },
11
  {
12
    type: 'intl-date',
13
    locale: 'de-DE',
14
    dateFormat: {
15
      dateStyle: 'long'
16
    }
17
  }
18
]

Date-specific options

Style shortcuts:

Property	Possible values	Description
`dateStyle`	`'full'`, `'long'`, `'medium'`, `'short'`	Date formatting style (weekday, day, month, year, era)
`timeStyle`	`'full'`, `'long'`, `'medium'`, `'short'`	Time part style (hour, minute, second, timeZoneName); use for date+time

Date-time component options:

Property	Possible values	Description
`weekday`	`'long'`, `'short'`, `'narrow'`	Weekday representation
`era`	`'long'`, `'short'`, `'narrow'`	Era representation
`year`	`'numeric'`, `'2-digit'`	Year representation
`month`	`'numeric'`, `'2-digit'`, `'long'`, `'short'`, `'narrow'`	Month representation
`day`	`'numeric'`, `'2-digit'`	Day representation
`dayPeriod`	`'narrow'`, `'short'`, `'long'`	Day period (e.g. “am”)
`hour`	`'numeric'`, `'2-digit'`	Hour (if time included)
`minute`	`'numeric'`, `'2-digit'`	Minute
`second`	`'numeric'`, `'2-digit'`	Second
`fractionalSecondDigits`	`1`, `2`, `3`	Fraction-of-second digits
`timeZoneName`	`'long'`, `'short'`, `'shortOffset'`, `'longOffset'`, `'shortGeneric'`, `'longGeneric'`	Time zone display

Locale and other options:

Property	Possible values	Description
`localeMatcher`	`'best fit'` (default), `'lookup'`	Locale matching algorithm
`calendar`	`'chinese'`, `'gregory'`, `'persian'`, etc.	Calendar to use
`numberingSystem`	`'latn'`, `'arab'`, `'hans'`, etc.	Numbering system
`timeZone`	IANA time zone (e.g. `'UTC'`, `'America/New_York'`)	Time zone for formatting
`hour12`	`true`, `false`	12-hour vs 24-hour time
`hourCycle`	`'h11'`, `'h12'`, `'h23'`, `'h24'`	Hour cycle
`formatMatcher`	`'basic'`, `'best fit'` (default)	Format matching algorithm

For a complete reference, see the dateFormat API documentation or MDN: Intl.DateTimeFormat.

Using string format with Moment.js (deprecated)

The date cell type with a string dateFormat is still supported but will be removed in next major release.

Deprecated options:

Option	Description	Replacement
`dateFormat` (string)	Moment.js format (e.g. `'DD/MM/YYYY'`)	Use `intl-date` with `dateFormat` object (see above)
`correctFormat`	Auto-correct entered date to match format	May be handled by `valueParser` and/or `valueSetter` options
`datePickerConfig`	Pikaday options for the date picker	`intl-date` uses a native date picker; no direct equivalent

Migration example:

1
// Before (deprecated)
2
columns: [{
3
  type: 'date',
4
  dateFormat: 'YYYY-MM-DD',
5
}]
6

7
// After (recommended)
8
columns: [{
9
  type: 'intl-date',
10
  locale: 'en-US',
11
  dateFormat: {
12
    year: 'numeric',
13
    month: '2-digit',
14
    day: '2-digit',
15
  }
16
}]

Editor behavior

The dateFormat option controls how dates are displayed in the cell. The editor (date picker or text input) may show the value in a normalized form; for intl-date, the underlying value remains in ISO 8601 format.

Related guides

Cell type

Configuration options

Core methods

Hooks