Date-time cell type

Display, format, sort, and filter combined date and time values by using the datetime cell type. Edit values via a native date-time picker.

The datetime cell type formats an ISO 8601 date-time value using a configurable Intl format. Use it for deadlines, timestamps, or any data that carries both a date and a time.

Overview

The datetime cell type lets you treat cell values as combined dates and times: format how they are displayed, edit them with a native picker, and validate input. Use the intl-datetime cell type with the native Intl.DateTimeFormat API and ISO 8601 date-time strings.

Date-time cell type demo

In the following demo, the Deadline and Created columns use the datetime cell type with different formats: a dateStyle/timeStyle shortcut, and a custom format with a 24-hour clock. Sorting and filtering operate on the underlying ISO values, so they stay correct regardless of the display format.

1
import { HotTable } from '@handsontable/react-wrapper';
2
import { registerAllModules } from 'handsontable/registry';
3
// register all of Handsontable's modules
4
registerAllModules();
5
const data = [
6
    { task: 'Design review', assignee: 'Ana García', deadline: '2024-03-15T09:30:00', created: '2024-03-01T08:00:00' },
7
    { task: 'Sprint demo', assignee: 'James Okafor', deadline: '2024-03-16 14:00:00', created: '2024-03-02T11:20:00' },
8
    { task: 'Release', assignee: 'Li Wei', deadline: '2024-03-20T23:59:59', created: '2024-03-05T16:45:00' },
9
    { task: 'Retro', assignee: 'Sofia Rossi', deadline: '2024-03-22', created: '2024-03-06T09:00:00' },
10
    { task: 'Planning', assignee: 'Noah Cohen', deadline: '2024-03-25T10:15:00', created: '2024-03-08T13:30:00' },
11
];
12
const ExampleComponent = () => {
13
    return (<HotTable data={data} colHeaders={['Task', 'Assignee', 'Deadline', 'Created']} columns={[
14
            { type: 'text', data: 'task', className: 'htLeft' },
15
            { type: 'text', data: 'assignee', className: 'htLeft' },
16
            {
17
                type: 'intl-datetime',
18
                data: 'deadline',
19
                className: 'htLeft',
20
                width: 190,
21
                locale: 'en-US',
22
                dateTimeFormat: { dateStyle: 'medium', timeStyle: 'short' },
23
            },
24
            {
25
                type: 'intl-datetime',
26
                data: 'created',
27
                className: 'htLeft',
28
                width: 165,
29
                locale: 'en-US',
30
                dateTimeFormat: {
31
                    year: 'numeric',
32
                    month: '2-digit',
33
                    day: '2-digit',
34
                    hour: '2-digit',
35
                    minute: '2-digit',
36
                    second: '2-digit',
37
                    hour12: false,
38
                },
39
            },
40
        ]} afterGetColHeader={(col, TH) => TH.classList.add('htLeft')} columnSorting={true} filters={true} dropdownMenu={true} stretchH="all" height="auto" autoWrapRow={true} autoWrapCol={true} licenseKey="non-commercial-and-evaluation"/>);
41
};
42
export default ExampleComponent;

1
import { HotTable } from '@handsontable/react-wrapper';
2
import { registerAllModules } from 'handsontable/registry';
3

4
// register all of Handsontable's modules
5
registerAllModules();
6

7
const data = [
8
  { task: 'Design review', assignee: 'Ana García', deadline: '2024-03-15T09:30:00', created: '2024-03-01T08:00:00' },
9
  { task: 'Sprint demo', assignee: 'James Okafor', deadline: '2024-03-16 14:00:00', created: '2024-03-02T11:20:00' },
10
  { task: 'Release', assignee: 'Li Wei', deadline: '2024-03-20T23:59:59', created: '2024-03-05T16:45:00' },
11
  { task: 'Retro', assignee: 'Sofia Rossi', deadline: '2024-03-22', created: '2024-03-06T09:00:00' },
12
  { task: 'Planning', assignee: 'Noah Cohen', deadline: '2024-03-25T10:15:00', created: '2024-03-08T13:30:00' },
13
];
14

15
const ExampleComponent = () => {
16
  return (
17
    <HotTable
18
      data={data}
19
      colHeaders={['Task', 'Assignee', 'Deadline', 'Created']}
20
      columns={[
21
        { type: 'text', data: 'task', className: 'htLeft' },
22
        { type: 'text', data: 'assignee', className: 'htLeft' },
23
        {
24
          type: 'intl-datetime',
25
          data: 'deadline',
26
          className: 'htLeft',
27
          width: 190,
28
          locale: 'en-US',
29
          dateTimeFormat: { dateStyle: 'medium', timeStyle: 'short' },
30
        },
31
        {
32
          type: 'intl-datetime',
33
          data: 'created',
34
          className: 'htLeft',
35
          width: 165,
36
          locale: 'en-US',
37
          dateTimeFormat: {
38
            year: 'numeric',
39
            month: '2-digit',
40
            day: '2-digit',
41
            hour: '2-digit',
42
            minute: '2-digit',
43
            second: '2-digit',
44
            hour12: false,
45
          },
46
        },
47
      ]}
48
      afterGetColHeader={(col: number, TH: HTMLTableCellElement) => TH.classList.add('htLeft')}
49
      columnSorting={true}
50
      filters={true}
51
      dropdownMenu={true}
52
      stretchH="all"
53
      height="auto"
54
      autoWrapRow={true}
55
      autoWrapCol={true}
56
      licenseKey="non-commercial-and-evaluation"
57
    />
58
  );
59
};
60

61
export default ExampleComponent;

Use the datetime cell type

Set the type option to 'intl-datetime' and dateTimeFormat to an object. The locale is controlled via the locale option.

1
// set the datetime cell type for the entire grid
2
type="intl-datetime"
3
locale="en-US"
4
dateTimeFormat={{
5
  dateStyle: 'medium',
6
  timeStyle: 'short'
7
}}
8

9
// set the datetime cell type for a single column
10
columns={[{
11
  type: 'intl-datetime',
12
  locale: 'en-US',
13
  dateTimeFormat: {
14
    year: 'numeric',
15
    month: '2-digit',
16
    day: '2-digit',
17
    hour: '2-digit',
18
    minute: '2-digit'
19
  }
20
}]}
21

22
// set the datetime cell type for a single cell
23
cell={[{
24
  row: 0,
25
  col: 1,
26
  type: 'intl-datetime',
27
  locale: 'en-US',
28
  dateTimeFormat: { dateStyle: 'short', timeStyle: 'short' }
29
}]}

For intl-datetime cells, source data must be in ISO 8601 date-time format (YYYY-MM-DDTHH:mm:ss) for values to work correctly. A date-only value (YYYY-MM-DD) is treated as midnight. The dateTimeFormat object only affects how values are displayed; sorting and filtering rely on the underlying ISO value.

Format date-time values

To control how values are displayed in cell renderers, use the dateTimeFormat option. It uses the native Intl.DateTimeFormat API. The locale is controlled separately via the locale option.

Using Intl.DateTimeFormat

The dateTimeFormat option accepts properties of Intl.DateTimeFormat options. Use it with type: 'intl-datetime'.

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 formatting style (hour, minute, second, timeZoneName)

Date-time component options:

Property	Possible values	Description
`weekday`	`'long'`, `'short'`, `'narrow'`	Weekday representation
`year`	`'numeric'`, `'2-digit'`	Year representation
`month`	`'numeric'`, `'2-digit'`, `'long'`, `'short'`, `'narrow'`	Month representation
`day`	`'numeric'`, `'2-digit'`	Day representation
`hour`	`'numeric'`, `'2-digit'`	Hour representation
`minute`	`'numeric'`, `'2-digit'`	Minute representation
`second`	`'numeric'`, `'2-digit'`	Second representation
`fractionalSecondDigits`	`1`, `2`, `3`	Fraction-of-second digits
`timeZoneName`	`'long'`, `'short'`, `'shortOffset'`, `'longOffset'`	Time zone display

Locale and other options:

Property	Possible values	Description
`localeMatcher`	`'best fit'` (default), `'lookup'`	Locale matching algorithm
`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

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

Editor behavior

Clicking an intl-datetime cell opens the browser’s native datetime-local picker. The editor shows the value in the YYYY-MM-DDTHH:mm:ss form the native input expects; on commit, the value is stored back in that ISO form. The dateTimeFormat option only affects the rendered display, not the stored value.

Result

After configuring the datetime cell type, cells display date-time values formatted according to your dateTimeFormat configuration. Clicking a cell opens a native date-time picker. Source data is stored in ISO 8601 format (YYYY-MM-DDTHH:mm:ss) regardless of the display format.

Keyboard shortcuts

The intl-datetime cell editor opens the browser’s native date-time picker. Keyboard navigation inside the picker comes from the browser, so it varies between browsers and operating systems. Outside the picker, the standard edition keyboard shortcuts apply.

Related guides

Cell type

Date cell type

Time cell type

Configuration options