Skip to content

Date-time cell type

Added in Handsontable 18.1.0

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.

JavaScript
import Handsontable from 'handsontable/base';
import { registerAllModules } from 'handsontable/registry';
// register all of Handsontable's modules
registerAllModules();
const container = document.querySelector('#example1');
const data = [
{ task: 'Design review', assignee: 'Ana García', deadline: '2024-03-15T09:30:00', created: '2024-03-01T08:00:00' },
{ task: 'Sprint demo', assignee: 'James Okafor', deadline: '2024-03-16 14:00:00', created: '2024-03-02T11:20:00' },
{ task: 'Release', assignee: 'Li Wei', deadline: '2024-03-20T23:59:59', created: '2024-03-05T16:45:00' },
{ task: 'Retro', assignee: 'Sofia Rossi', deadline: '2024-03-22', created: '2024-03-06T09:00:00' },
{ task: 'Planning', assignee: 'Noah Cohen', deadline: '2024-03-25T10:15:00', created: '2024-03-08T13:30:00' },
];
new Handsontable(container, {
data,
colHeaders: ['Task', 'Assignee', 'Deadline', 'Created'],
columns: [
{ type: 'text', data: 'task', className: 'htLeft' },
{ type: 'text', data: 'assignee', className: 'htLeft' },
{
type: 'intl-datetime',
data: 'deadline',
className: 'htLeft',
width: 190,
locale: 'en-US',
dateTimeFormat: {
dateStyle: 'medium',
timeStyle: 'short',
},
},
{
type: 'intl-datetime',
data: 'created',
className: 'htLeft',
width: 165,
locale: 'en-US',
dateTimeFormat: {
year: 'numeric',
month: '2-digit',
day: '2-digit',
hour: '2-digit',
minute: '2-digit',
second: '2-digit',
hour12: false,
},
},
],
// left-align the column headers (a column's `className` only aligns cell content)
afterGetColHeader(col, TH) {
TH.classList.add('htLeft');
},
columnSorting: true,
filters: true,
dropdownMenu: true,
stretchH: 'all',
height: 'auto',
autoWrapRow: true,
autoWrapCol: true,
// licenseKey: 'your-license-key', // get a key at https://handsontable.com/pricing/
});
TypeScript
import Handsontable from 'handsontable/base';
import { registerAllModules } from 'handsontable/registry';
// register all of Handsontable's modules
registerAllModules();
const container = document.querySelector('#example1')!;
const data = [
{ task: 'Design review', assignee: 'Ana García', deadline: '2024-03-15T09:30:00', created: '2024-03-01T08:00:00' },
{ task: 'Sprint demo', assignee: 'James Okafor', deadline: '2024-03-16 14:00:00', created: '2024-03-02T11:20:00' },
{ task: 'Release', assignee: 'Li Wei', deadline: '2024-03-20T23:59:59', created: '2024-03-05T16:45:00' },
{ task: 'Retro', assignee: 'Sofia Rossi', deadline: '2024-03-22', created: '2024-03-06T09:00:00' },
{ task: 'Planning', assignee: 'Noah Cohen', deadline: '2024-03-25T10:15:00', created: '2024-03-08T13:30:00' },
];
new Handsontable(container, {
data,
colHeaders: ['Task', 'Assignee', 'Deadline', 'Created'],
columns: [
{ type: 'text', data: 'task', className: 'htLeft' },
{ type: 'text', data: 'assignee', className: 'htLeft' },
{
type: 'intl-datetime',
data: 'deadline',
className: 'htLeft',
width: 190,
locale: 'en-US',
dateTimeFormat: {
dateStyle: 'medium',
timeStyle: 'short',
},
},
{
type: 'intl-datetime',
data: 'created',
className: 'htLeft',
width: 165,
locale: 'en-US',
dateTimeFormat: {
year: 'numeric',
month: '2-digit',
day: '2-digit',
hour: '2-digit',
minute: '2-digit',
second: '2-digit',
hour12: false,
},
},
],
// left-align the column headers (a column's `className` only aligns cell content)
afterGetColHeader(col: number, TH: HTMLTableCellElement) {
TH.classList.add('htLeft');
},
columnSorting: true,
filters: true,
dropdownMenu: true,
stretchH: 'all',
height: 'auto',
autoWrapRow: true,
autoWrapCol: true,
// licenseKey: 'your-license-key', // get a key at https://handsontable.com/pricing/
});
HTML
<div id="example1"></div>

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.

// set the datetime cell type for the entire grid
type: 'intl-datetime',
locale: 'en-US',
dateTimeFormat: {
dateStyle: 'medium',
timeStyle: 'short'
},
// set the datetime cell type for a single column
columns: [
{
type: 'intl-datetime',
locale: 'en-US',
dateTimeFormat: {
year: 'numeric',
month: '2-digit',
day: '2-digit',
hour: '2-digit',
minute: '2-digit'
}
}
],
// set the datetime cell type for a single cell
cell: [
{
row: 0,
col: 1,
type: 'intl-datetime',
locale: 'en-US',
dateTimeFormat: { dateStyle: 'short', timeStyle: 'short' }
}
],

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:

PropertyPossible valuesDescription
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:

PropertyPossible valuesDescription
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
fractionalSecondDigits1, 2, 3Fraction-of-second digits
timeZoneName'long', 'short', 'shortOffset', 'longOffset'Time zone display

Locale and other options:

PropertyPossible valuesDescription
localeMatcher'best fit' (default), 'lookup'Locale matching algorithm
timeZoneIANA time zone (e.g. 'UTC', 'America/New_York')Time zone for formatting
hour12true, false12-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.

Year 0000

ISO 8601 uses year 0000 for 1 BC. A value in year 0000 is valid, and it sorts before 0001-01-01T00:00:00. Intl.DateTimeFormat prints that year as 1, the same as year 0001. To tell them apart, Handsontable adds the era to the display of year 0000. It does so when the format prints a year and sets no era of its own. For example, 0000-01-01T00:00:00 shows as 01/01/1 BC, 00:00:00 and 0001-01-01T00:00:00 shows as 01/01/1, 00:00:00. The era text follows the locale. A format that uses dateStyle or timeStyle cannot carry an era, so it still prints year 0000 as 1.

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. Double-clicking a cell shows the picker. In Chromium-based browsers, an open picker takes the keys: Tab does nothing, and Enter and Escape close only the picker. Opening the editor with the keyboard (Enter, F2, or typing) leaves the picker closed, so Tab, Escape, and the other grid shortcuts keep working. In Chrome and Edge, press Alt+↓ (⌥+↓ on macOS) in the editor to show the 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

Configuration options

Core methods

Hooks