Skip to content
Handsontable

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.

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: 'non-commercial-and-evaluation',
});
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: 'non-commercial-and-evaluation',
});
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.

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

dateTimeFormat
locale
type
valueFormatter
valueParser
valueSetter
valueGetter

Core methods

getCellMeta()
getCellMetaAtRow()
getCellsMeta()
getDataType()
setCellMeta()
setCellMetaObject()
removeCellMeta()

Hooks

afterGetCellMeta
afterSetCellMeta
beforeGetCellMeta
beforeSetCellMeta