Time cell type

Display, format, sort, and filter time values correctly by using the time cell type. Edit times via the cell editor.

Overview

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

Time cell type demo

In the following demo, the Start, Break start, and End columns use the time cell type with different formats: short style, custom format with hours, minutes, and seconds, and format with day period. Use the locale selector to see how each format varies by locale.

1
import { useRef, useState, useEffect } from 'react';
2
import { HotTable } from '@handsontable/react-wrapper';
3
import { registerAllModules } from 'handsontable/registry';
4

5
// register Handsontable's modules
6
registerAllModules();
7

23 collapsed lines
8
const localeOptions = [
9
  { value: 'ar-AR', label: 'Arabic (Global)' },
10
  { value: 'cs-CZ', label: 'Czech (Czechia)' },
11
  { value: 'de-CH', label: 'German (Switzerland)' },
12
  { value: 'de-DE', label: 'German (Germany)' },
13
  { value: 'en-US', label: 'English (United States)' },
14
  { value: 'es-MX', label: 'Spanish (Mexico)' },
15
  { value: 'fa-IR', label: 'Persian (Iran)' },
16
  { value: 'fr-FR', label: 'French (France)' },
17
  { value: 'hr-HR', label: 'Croatian (Croatia)' },
18
  { value: 'it-IT', label: 'Italian (Italy)' },
19
  { value: 'ja-JP', label: 'Japanese (Japan)' },
20
  { value: 'ko-KR', label: 'Korean (Korea)' },
21
  { value: 'lv-LV', label: 'Latvian (Latvia)' },
22
  { value: 'nb-NO', label: 'Norwegian Bokmal (Norway)' },
23
  { value: 'nl-NL', label: 'Dutch (Netherlands)' },
24
  { value: 'pl-PL', label: 'Polish (Poland)' },
25
  { value: 'pt-BR', label: 'Portuguese (Brazil)' },
26
  { value: 'ru-RU', label: 'Russian (Russia)' },
27
  { value: 'sr-SP', label: 'Serbian Latin (Serbia)' },
28
  { value: 'zh-CN', label: 'Chinese (Simplified, China)' },
29
  { value: 'zh-TW', label: 'Chinese (Traditional, Taiwan)' },
30
];
31

32
const ExampleComponent = () => {
33
  const hotRef = useRef(null);
34
  const dropdownRef = useRef(null);
35
  const [isOpen, setIsOpen] = useState(false);
36
  const [locale, setLocale] = useState('en-US');
37

38
  useEffect(() => {
39
    const handleOutsideClick = (e) => {
40
      if (dropdownRef.current && !dropdownRef.current.contains(e.target)) {
41
        setIsOpen(false);
42
      }
43
    };
44
    const handleEscape = (e) => {
45
      if (e.key === 'Escape') {
46
        setIsOpen(false);
47
      }
48
    };
49

50
    document.addEventListener('click', handleOutsideClick);
51
    document.addEventListener('keydown', handleEscape);
52

53
    return () => {
54
      document.removeEventListener('click', handleOutsideClick);
55
      document.removeEventListener('keydown', handleEscape);
56
    };
57
  }, []);
58

59
  const handleSelect = (value) => {
60
    setLocale(value);
61
    setIsOpen(false);
62
    hotRef.current?.hotInstance?.updateSettings({ locale: value });
63
  };
64

65
  const selectedLabel = localeOptions.find((o) => o.value === locale)?.label;
66

7 collapsed lines
67
  const data = [
68
    { shift: 'Morning', start: '09:00', breakStart: '12:00', end: '17:00' },
69
    { shift: 'Afternoon', start: '13:30', breakStart: '16:00', end: '21:00' },
70
    { shift: 'Night', start: '22:00', breakStart: '01:00', end: '06:00' },
71
    { shift: 'Split', start: '08:00', breakStart: '12:30', end: '20:00' },
72
    { shift: 'Short day', start: '10:00', breakStart: '13:00', end: '15:00' },
73
  ];
74

75
  return (
76
    <>
77
      <div className="example-controls-container">
78
        <div className="controls">
79
          <div className="theme-dropdown" ref={dropdownRef}>
80
            <button
81
              className="theme-dropdown-trigger"
82
              type="button"
83
              aria-haspopup="listbox"
84
              aria-expanded={isOpen}
85
              onClick={() => setIsOpen(!isOpen)}
86
            >
87
              <span>{selectedLabel}</span>
88
              <svg className="theme-dropdown-chevron" aria-hidden="true" width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><path d="M6 9l6 6l6 -6"/></svg>
89
            </button>
90
            {isOpen && (
91
              <ul className="theme-dropdown-menu" role="listbox">
92
                {localeOptions.map((opt) => (
93
                  <li
94
                    key={opt.value}
95
                    role="option"
96
                    aria-selected={locale === opt.value}
97
                    onClick={() => handleSelect(opt.value)}
98
                  >
99
                    {opt.label}
100
                  </li>
101
                ))}
102
              </ul>
103
            )}
104
          </div>
105
        </div>
106
      </div>
107

108
      <HotTable
109
        ref={hotRef}
110
        data={data}
111
        colHeaders={['Shift', 'Start', 'Break start', 'End']}
112
        locale={locale}
31 collapsed lines
113
        columns={[
114
          {
115
            type: 'text',
116
            data: 'shift',
117
          },
118
          {
119
            type: 'intl-time',
120
            data: 'start',
121
            timeFormat: {
122
              timeStyle: 'short',
123
            },
124
          },
125
          {
126
            type: 'intl-time',
127
            data: 'breakStart',
128
            timeFormat: {
129
              hour: '2-digit',
130
              minute: '2-digit',
131
              second: '2-digit',
132
            },
133
          },
134
          {
135
            type: 'intl-time',
136
            data: 'end',
137
            timeFormat: {
138
              hour: 'numeric',
139
              hourCycle: 'h12',
140
              dayPeriod: 'short',
141
            },
142
          },
143
        ]}
144
        columnSorting={true}
145
        filters={true}
146
        dropdownMenu={true}
147
        height="auto"
148
        autoWrapRow={true}
149
        autoWrapCol={true}
150
        licenseKey="non-commercial-and-evaluation"
151
      />
152
    </>
153
  );
154
};
155

156
export default ExampleComponent;

1
import { useRef, useState, useEffect } from 'react';
2
import Handsontable from 'handsontable/base';
3
import { HotTable, HotTableRef } from '@handsontable/react-wrapper';
4
import { registerAllModules } from 'handsontable/registry';
5

6
// register Handsontable's modules
7
registerAllModules();
8

23 collapsed lines
9
const localeOptions: { value: string; label: string }[] = [
10
  { value: 'ar-AR', label: 'Arabic (Global)' },
11
  { value: 'cs-CZ', label: 'Czech (Czechia)' },
12
  { value: 'de-CH', label: 'German (Switzerland)' },
13
  { value: 'de-DE', label: 'German (Germany)' },
14
  { value: 'en-US', label: 'English (United States)' },
15
  { value: 'es-MX', label: 'Spanish (Mexico)' },
16
  { value: 'fa-IR', label: 'Persian (Iran)' },
17
  { value: 'fr-FR', label: 'French (France)' },
18
  { value: 'hr-HR', label: 'Croatian (Croatia)' },
19
  { value: 'it-IT', label: 'Italian (Italy)' },
20
  { value: 'ja-JP', label: 'Japanese (Japan)' },
21
  { value: 'ko-KR', label: 'Korean (Korea)' },
22
  { value: 'lv-LV', label: 'Latvian (Latvia)' },
23
  { value: 'nb-NO', label: 'Norwegian Bokmal (Norway)' },
24
  { value: 'nl-NL', label: 'Dutch (Netherlands)' },
25
  { value: 'pl-PL', label: 'Polish (Poland)' },
26
  { value: 'pt-BR', label: 'Portuguese (Brazil)' },
27
  { value: 'ru-RU', label: 'Russian (Russia)' },
28
  { value: 'sr-SP', label: 'Serbian Latin (Serbia)' },
29
  { value: 'zh-CN', label: 'Chinese (Simplified, China)' },
30
  { value: 'zh-TW', label: 'Chinese (Traditional, Taiwan)' },
31
];
32

33
const ExampleComponent = () => {
34
  const hotRef = useRef<HotTableRef>(null);
35
  const dropdownRef = useRef<HTMLDivElement>(null);
36
  const [isOpen, setIsOpen] = useState(false);
37
  const [locale, setLocale] = useState('en-US');
38

39
  useEffect(() => {
40
    const handleOutsideClick = (e: MouseEvent) => {
41
      if (dropdownRef.current && !dropdownRef.current.contains(e.target as Node)) {
42
        setIsOpen(false);
43
      }
44
    };
45
    const handleEscape = (e: KeyboardEvent) => {
46
      if (e.key === 'Escape') {
47
        setIsOpen(false);
48
      }
49
    };
50

51
    document.addEventListener('click', handleOutsideClick);
52
    document.addEventListener('keydown', handleEscape);
53

54
    return () => {
55
      document.removeEventListener('click', handleOutsideClick);
56
      document.removeEventListener('keydown', handleEscape);
57
    };
58
  }, []);
59

60
  const handleSelect = (value: string) => {
61
    setLocale(value);
62
    setIsOpen(false);
63
    hotRef.current?.hotInstance?.updateSettings({ locale: value } as Handsontable.GridSettings);
64
  };
65

66
  const selectedLabel = localeOptions.find((o) => o.value === locale)?.label;
67

7 collapsed lines
68
  const data = [
69
    { shift: 'Morning', start: '09:00', breakStart: '12:00', end: '17:00' },
70
    { shift: 'Afternoon', start: '13:30', breakStart: '16:00', end: '21:00' },
71
    { shift: 'Night', start: '22:00', breakStart: '01:00', end: '06:00' },
72
    { shift: 'Split', start: '08:00', breakStart: '12:30', end: '20:00' },
73
    { shift: 'Short day', start: '10:00', breakStart: '13:00', end: '15:00' },
74
  ];
75

76
  return (
77
    <>
78
      <div className="example-controls-container">
79
        <div className="controls">
80
          <div className="theme-dropdown" ref={dropdownRef}>
81
            <button
82
              className="theme-dropdown-trigger"
83
              type="button"
84
              aria-haspopup="listbox"
85
              aria-expanded={isOpen}
86
              onClick={() => setIsOpen(!isOpen)}
87
            >
88
              <span>{selectedLabel}</span>
89
              <svg className="theme-dropdown-chevron" aria-hidden="true" width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><path d="M6 9l6 6l6 -6"/></svg>
90
            </button>
91
            {isOpen && (
92
              <ul className="theme-dropdown-menu" role="listbox">
93
                {localeOptions.map((opt) => (
94
                  <li
95
                    key={opt.value}
96
                    role="option"
97
                    aria-selected={locale === opt.value}
98
                    onClick={() => handleSelect(opt.value)}
99
                  >
100
                    {opt.label}
101
                  </li>
102
                ))}
103
              </ul>
104
            )}
105
          </div>
106
        </div>
107
      </div>
108

109
      <HotTable
110
        ref={hotRef}
111
        data={data}
112
        colHeaders={['Shift', 'Start', 'Break start', 'End']}
113
        locale={locale}
31 collapsed lines
114
        columns={[
115
          {
116
            type: 'text',
117
            data: 'shift',
118
          },
119
          {
120
            type: 'intl-time',
121
            data: 'start',
122
            timeFormat: {
123
              timeStyle: 'short',
124
            },
125
          },
126
          {
127
            type: 'intl-time',
128
            data: 'breakStart',
129
            timeFormat: {
130
              hour: '2-digit',
131
              minute: '2-digit',
132
              second: '2-digit',
133
            },
134
          },
135
          {
136
            type: 'intl-time',
137
            data: 'end',
138
            timeFormat: {
139
              hour: 'numeric',
140
              hourCycle: 'h12',
141
              dayPeriod: 'short',
142
            },
143
          },
144
        ]}
145
        columnSorting={true}
146
        filters={true}
147
        dropdownMenu={true}
148
        height="auto"
149
        autoWrapRow={true}
150
        autoWrapCol={true}
151
        licenseKey="non-commercial-and-evaluation"
152
      />
153
    </>
154
  );
155
};
156

157
export default ExampleComponent;

Use the time cell type

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

1
// set the time cell type for the entire grid (Intl, recommended)
2
type="intl-time"
3
locale="en-US"
4
timeFormat={{
5
  hour: 'numeric',
6
  minute: '2-digit',
7
  second: '2-digit',
8
  hour12: true
9
}}
10

11
// set the time cell type for a single column
12
columns={[{
13
  type: 'intl-time',
14
  locale: 'en-US',
15
  timeFormat: { timeStyle: 'medium' }
16
}]}
17

18
// set the time cell type for a single cell
19
cell={[{
20
  row: 0,
21
  col: 2,
22
  type: 'intl-time',
23
  locale: 'en-US',
24
  timeFormat: { hour: '2-digit', minute: '2-digit', hour12: true }
25
}]}

For intl-time cells, source data must be in 24-hour time format (HH:mm, HH:mm:ss, or HH:mm:ss.SSS) for times to work correctly. The timeFormat object only affects how times are displayed; sorting and filtering rely on the underlying value.

Format times

To control how times are displayed in cell renderers, use the timeFormat option.

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

Using Intl.DateTimeFormat (recommended)

The timeFormat option accepts properties of Intl.DateTimeFormat options relevant to time. Use it with type: 'intl-time'.

1
<HotTable
2
  columns={[{
3
    type: 'intl-time',
4
    locale: 'en-US',
5
    timeFormat: {
6
      hour: 'numeric',
7
      minute: '2-digit',
8
      second: '2-digit',
9
      hour12: true
10
    }
11
  }, {
12
    type: 'intl-time',
13
    locale: 'de-DE',
14
    timeFormat: { timeStyle: 'medium' }
15
  }]}
16
/>

Time-specific options

Style shortcuts:

Property	Possible values	Description
`timeStyle`	`'full'`, `'long'`, `'medium'`, `'short'`	Time formatting style (hour, minute, second, timeZoneName)

Time component options:

Property	Possible values	Description
`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
`dayPeriod`	`'narrow'`, `'short'`, `'long'`	Day period (e.g. “am”)
`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
`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 timeFormat API documentation or MDN: Intl.DateTimeFormat.

Using string format with Moment.js (deprecated)

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

Deprecated options:

Option	Description	Replacement
`timeFormat` (string)	Moment.js format (e.g. `'h:mm:ss a'`)	Use `intl-time` with `timeFormat` object (see above)
`correctFormat`	Auto-correct entered time to match format	May be handled by `valueParser` and/or `valueSetter` options

Migration example:

1
// Before (deprecated)
2
columns: [{
3
  type: 'time',
4
  timeFormat: 'h:mm:ss a',
5
}]
6

7
// After (recommended)
8
columns: [{
9
  type: 'intl-time',
10
  locale: 'en-US',
11
  timeFormat: {
12
    hour: 'numeric',
13
    minute: '2-digit',
14
    second: '2-digit',
15
    hour12: true,
16
  }
17
}]

Editor behavior

The timeFormat option controls how times are displayed in the cell. The editor may show the value in a normalized form; for intl-time, the underlying value remains in 24-hour format (HH:mm, HH:mm:ss, or HH:mm:ss.SSS).

Related guides

Cell type

Configuration options

Core methods

Hooks