React Data GridDate cell type

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

Overview
Date cell type demo
Use the date cell type
Format dates
Related articles
- Related guides
- Related API reference

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 (opens new window) API (recommended), and a string-style configuration using Moment.js (opens new window) (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

{
  "name": "handsontable",
  "version": "1.0.0",
  "description": "",
  "dependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "hyperformula": "^3.0.0",
    "handsontable": "17.0",
    "@handsontable/react-wrapper": "17.0"
  },
  
  "browserslist": {
    "production": [
      ">0.2%",
      "not dead",
      "not op_mini all"
    ],
    "development": [
      "last 1 chrome version",
      "last 1 firefox version",
      "last 1 safari version"
    ]
  }
}

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Handsontable</title>
  </head>

  <body>
    <noscript> You need to enable JavaScript to run this app. </noscript>
    <div id="root" class=""></div>
  </body>
</html>

import React, { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import "./styles.css";
import ExampleComponent from "./ExampleComponent";

const rootElement = document.getElementById("root");
const root = createRoot(rootElement);

root.render(
  <StrictMode>
    <ExampleComponent />
  </StrictMode>
);

import React from "react";
import { useState } from 'react';
import { HotTable } from '@handsontable/react-wrapper';
import { registerAllModules } from 'handsontable/registry';

// register Handsontable's modules
registerAllModules();

const ExampleComponent = () => {
  const [locale, setLocale] = useState('en-US');
  const data = [
    {
      car: 'Mercedes A 160',
      product_date: '2002-06-15',
      payment_date: '2002-05-20',
      registration_date: '2002-07-01',
    },
    {
      car: 'Citroën C4 Coupe',
      product_date: '2007-03-22',
      payment_date: '2007-02-28',
      registration_date: '2007-04-10',
    },
    {
      car: 'Audi A4 Avant',
      product_date: '2011-09-08',
      payment_date: '2011-08-15',
      registration_date: '2011-09-20',
    },
    {
      car: 'Opel Astra',
      product_date: '2012-01-30',
      payment_date: '2012-01-10',
      registration_date: '2012-02-14',
    },
    {
      car: 'BMW 320i Coupe',
      product_date: '2004-11-12',
      payment_date: '2004-10-20',
      registration_date: '2004-12-01',
    },
  ];

  const handleLocaleChange = (event) => {
    setLocale(event.target.value);
  };

  return (
    <>
      <div className="example-controls-container">
        <div className="controls">
          <label>
            Select locale:
            <select id="localeSelect" value={locale} onChange={handleLocaleChange}>
              <option value="ar-AR">Arabic (Global)</option>
              <option value="cs-CZ">Czech (Czechia)</option>
              <option value="de-CH">German (Switzerland)</option>
              <option value="de-DE">German (Germany)</option>
              <option value="en-US">English (United States)</option>
              <option value="es-MX">Spanish (Mexico)</option>
              <option value="fa-IR">Persian (Iran)</option>
              <option value="fr-FR">French (France)</option>
              <option value="hr-HR">Croatian (Croatia)</option>
              <option value="it-IT">Italian (Italy)</option>
              <option value="ja-JP">Japanese (Japan)</option>
              <option value="ko-KR">Korean (Korea)</option>
              <option value="lv-LV">Latvian (Latvia)</option>
              <option value="nb-NO">Norwegian Bokmal (Norway)</option>
              <option value="nl-NL">Dutch (Netherlands)</option>
              <option value="pl-PL">Polish (Poland)</option>
              <option value="pt-BR">Portuguese (Brazil)</option>
              <option value="ru-RU">Russian (Russia)</option>
              <option value="sr-SP">Serbian Latin (Serbia)</option>
              <option value="zh-CN">Chinese (Simplified, China)</option>
              <option value="zh-TW">Chinese (Traditional, Taiwan)</option>
            </select>
          </label>
        </div>
      </div>

      <style>{`
        .example-controls-container .controls {
          padding-top: 0;
          display: flex;
          align-items: center;
          gap: 10px;
        }

        .example-controls-container .controls label {
          display: flex;
          align-items: center;
          gap: 8px;
          font-size: 14px;
        }

        .example-controls-container .controls select {
          padding: 6px 12px;
          border: 1px solid #ccc;
          border-radius: 4px;
          font-size: 14px;
          cursor: pointer;
        }

        .example-controls-container .controls select:hover {
          border-color: #999;
        }

        .example-controls-container .controls select:focus {
          outline: none;
          border-color: #0066cc;
          box-shadow: 0 0 0 2px rgba(0, 102, 204, 0.2);
        }
      `}</style>

      <HotTable
        data={data}
        colHeaders={['Car', 'Product date', 'Payment date', 'Registration date']}
        locale={locale}
        columns={[
          {
            type: 'text',
            data: 'car',
          },
          {
            type: 'intl-date',
            data: 'product_date',
            dateFormat: { dateStyle: 'short' },
          },
          {
            type: 'intl-date',
            data: 'payment_date',
            dateFormat: {
              month: 'long',
              day: 'numeric',
              year: 'numeric',
            },
          },
          {
            type: 'intl-date',
            data: 'registration_date',
            dateFormat: {
              weekday: 'long',
              year: 'numeric',
              month: 'long',
              day: 'numeric',
            },
          },
        ]}
        columnSorting={true}
        filters={true}
        dropdownMenu={true}
        height="auto"
        autoWrapRow={true}
        autoWrapCol={true}
        licenseKey="non-commercial-and-evaluation"
      />
    </>
  );
};

export default ExampleComponent;

import { useState } from 'react';
import { HotTable } from '@handsontable/react-wrapper';
import { registerAllModules } from 'handsontable/registry';

// register Handsontable's modules
registerAllModules();

const ExampleComponent = () => {
  const [locale, setLocale] = useState('en-US');
  const data = [
    {
      car: 'Mercedes A 160',
      product_date: '2002-06-15',
      payment_date: '2002-05-20',
      registration_date: '2002-07-01',
    },
    {
      car: 'Citroën C4 Coupe',
      product_date: '2007-03-22',
      payment_date: '2007-02-28',
      registration_date: '2007-04-10',
    },
    {
      car: 'Audi A4 Avant',
      product_date: '2011-09-08',
      payment_date: '2011-08-15',
      registration_date: '2011-09-20',
    },
    {
      car: 'Opel Astra',
      product_date: '2012-01-30',
      payment_date: '2012-01-10',
      registration_date: '2012-02-14',
    },
    {
      car: 'BMW 320i Coupe',
      product_date: '2004-11-12',
      payment_date: '2004-10-20',
      registration_date: '2004-12-01',
    },
  ];

  const handleLocaleChange = (event) => {
    setLocale(event.target.value);
  };

  return (
    <>
      <div className="example-controls-container">
        <div className="controls">
          <label>
            Select locale:
            <select id="localeSelect" value={locale} onChange={handleLocaleChange}>
              <option value="ar-AR">Arabic (Global)</option>
              <option value="cs-CZ">Czech (Czechia)</option>
              <option value="de-CH">German (Switzerland)</option>
              <option value="de-DE">German (Germany)</option>
              <option value="en-US">English (United States)</option>
              <option value="es-MX">Spanish (Mexico)</option>
              <option value="fa-IR">Persian (Iran)</option>
              <option value="fr-FR">French (France)</option>
              <option value="hr-HR">Croatian (Croatia)</option>
              <option value="it-IT">Italian (Italy)</option>
              <option value="ja-JP">Japanese (Japan)</option>
              <option value="ko-KR">Korean (Korea)</option>
              <option value="lv-LV">Latvian (Latvia)</option>
              <option value="nb-NO">Norwegian Bokmal (Norway)</option>
              <option value="nl-NL">Dutch (Netherlands)</option>
              <option value="pl-PL">Polish (Poland)</option>
              <option value="pt-BR">Portuguese (Brazil)</option>
              <option value="ru-RU">Russian (Russia)</option>
              <option value="sr-SP">Serbian Latin (Serbia)</option>
              <option value="zh-CN">Chinese (Simplified, China)</option>
              <option value="zh-TW">Chinese (Traditional, Taiwan)</option>
            </select>
          </label>
        </div>
      </div>

      <style>{`
        .example-controls-container .controls {
          padding-top: 0;
          display: flex;
          align-items: center;
          gap: 10px;
        }

        .example-controls-container .controls label {
          display: flex;
          align-items: center;
          gap: 8px;
          font-size: 14px;
        }

        .example-controls-container .controls select {
          padding: 6px 12px;
          border: 1px solid #ccc;
          border-radius: 4px;
          font-size: 14px;
          cursor: pointer;
        }

        .example-controls-container .controls select:hover {
          border-color: #999;
        }

        .example-controls-container .controls select:focus {
          outline: none;
          border-color: #0066cc;
          box-shadow: 0 0 0 2px rgba(0, 102, 204, 0.2);
        }
      `}</style>

      <HotTable
        data={data}
        colHeaders={['Car', 'Product date', 'Payment date', 'Registration date']}
        locale={locale}
        columns={[
          {
            type: 'text',
            data: 'car',
          },
          {
            type: 'intl-date',
            data: 'product_date',
            dateFormat: { dateStyle: 'short' },
          },
          {
            type: 'intl-date',
            data: 'payment_date',
            dateFormat: {
              month: 'long',
              day: 'numeric',
              year: 'numeric',
            },
          },
          {
            type: 'intl-date',
            data: 'registration_date',
            dateFormat: {
              weekday: 'long',
              year: 'numeric',
              month: 'long',
              day: 'numeric',
            },
          },
        ]}
        columnSorting={true}
        filters={true}
        dropdownMenu={true}
        height="auto"
        autoWrapRow={true}
        autoWrapCol={true}
        licenseKey="non-commercial-and-evaluation"
      />
    </>
  );
};



const container = document.getElementById("example1");
const root = ReactDOM.createRoot(container);
container._reactRoot = root;
root.render(<ExampleComponent />);

<script src="https://cdn.jsdelivr.net/npm/handsontable@17.0/dist/handsontable.full.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/react@18/umd/react.production.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/react-dom@18/umd/react-dom.production.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@handsontable/react-wrapper@17.0/dist/react-handsontable.min.js"></script>
<script src="https://handsontable.com/docs/17.0/scripts/fixer.js"></script>

<div id="example1" class="hot"></div>

import { useState } from 'react';
import { HotTable } from '@handsontable/react-wrapper';
import { registerAllModules } from 'handsontable/registry';

// register Handsontable's modules
registerAllModules();

const ExampleComponent = () => {
  const [locale, setLocale] = useState('en-US');
  const data = [
    {
      car: 'Mercedes A 160',
      product_date: '2002-06-15',
      payment_date: '2002-05-20',
      registration_date: '2002-07-01',
    },
    {
      car: 'Citroën C4 Coupe',
      product_date: '2007-03-22',
      payment_date: '2007-02-28',
      registration_date: '2007-04-10',
    },
    {
      car: 'Audi A4 Avant',
      product_date: '2011-09-08',
      payment_date: '2011-08-15',
      registration_date: '2011-09-20',
    },
    {
      car: 'Opel Astra',
      product_date: '2012-01-30',
      payment_date: '2012-01-10',
      registration_date: '2012-02-14',
    },
    {
      car: 'BMW 320i Coupe',
      product_date: '2004-11-12',
      payment_date: '2004-10-20',
      registration_date: '2004-12-01',
    },
  ];

  const handleLocaleChange = (event) => {
    setLocale(event.target.value);
  };

  return (
    <>
      <div className="example-controls-container">
        <div className="controls">
          <label>
            Select locale:
            <select id="localeSelect" value={locale} onChange={handleLocaleChange}>
              <option value="ar-AR">Arabic (Global)</option>
              <option value="cs-CZ">Czech (Czechia)</option>
              <option value="de-CH">German (Switzerland)</option>
              <option value="de-DE">German (Germany)</option>
              <option value="en-US">English (United States)</option>
              <option value="es-MX">Spanish (Mexico)</option>
              <option value="fa-IR">Persian (Iran)</option>
              <option value="fr-FR">French (France)</option>
              <option value="hr-HR">Croatian (Croatia)</option>
              <option value="it-IT">Italian (Italy)</option>
              <option value="ja-JP">Japanese (Japan)</option>
              <option value="ko-KR">Korean (Korea)</option>
              <option value="lv-LV">Latvian (Latvia)</option>
              <option value="nb-NO">Norwegian Bokmal (Norway)</option>
              <option value="nl-NL">Dutch (Netherlands)</option>
              <option value="pl-PL">Polish (Poland)</option>
              <option value="pt-BR">Portuguese (Brazil)</option>
              <option value="ru-RU">Russian (Russia)</option>
              <option value="sr-SP">Serbian Latin (Serbia)</option>
              <option value="zh-CN">Chinese (Simplified, China)</option>
              <option value="zh-TW">Chinese (Traditional, Taiwan)</option>
            </select>
          </label>
        </div>
      </div>

      <style>{`
        .example-controls-container .controls {
          padding-top: 0;
          display: flex;
          align-items: center;
          gap: 10px;
        }

        .example-controls-container .controls label {
          display: flex;
          align-items: center;
          gap: 8px;
          font-size: 14px;
        }

        .example-controls-container .controls select {
          padding: 6px 12px;
          border: 1px solid #ccc;
          border-radius: 4px;
          font-size: 14px;
          cursor: pointer;
        }

        .example-controls-container .controls select:hover {
          border-color: #999;
        }

        .example-controls-container .controls select:focus {
          outline: none;
          border-color: #0066cc;
          box-shadow: 0 0 0 2px rgba(0, 102, 204, 0.2);
        }
      `}</style>

      <HotTable
        data={data}
        colHeaders={['Car', 'Product date', 'Payment date', 'Registration date']}
        locale={locale}
        columns={[
          {
            type: 'text',
            data: 'car',
          },
          {
            type: 'intl-date',
            data: 'product_date',
            dateFormat: { dateStyle: 'short' },
          },
          {
            type: 'intl-date',
            data: 'payment_date',
            dateFormat: {
              month: 'long',
              day: 'numeric',
              year: 'numeric',
            },
          },
          {
            type: 'intl-date',
            data: 'registration_date',
            dateFormat: {
              weekday: 'long',
              year: 'numeric',
              month: 'long',
              day: 'numeric',
            },
          },
        ]}
        columnSorting={true}
        filters={true}
        dropdownMenu={true}
        height="auto"
        autoWrapRow={true}
        autoWrapCol={true}
        licenseKey="non-commercial-and-evaluation"
      />
    </>
  );
};

export default ExampleComponent;

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.

// set the date cell type for the entire grid (Intl, recommended)
type="intl-date"
locale="en-US"
dateFormat={{
  year: 'numeric',
  month: '2-digit',
  day: '2-digit'
}}

// set the date cell type for a single column
columns={[{
  type: 'intl-date',
  locale: 'en-US',
  dateFormat: { dateStyle: 'short' }
}]}

// set the date cell type for a single cell
cell={[{
  row: 0,
  col: 2,
  type: 'intl-date',
  locale: 'en-US',
  dateFormat: { dateStyle: 'medium' }
}]}

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 (opens new window) API. The locale is controlled separately via the locale option.

Using Intl.DateTimeFormat (recommended)

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

<HotTable
  columns={[{
    type: 'intl-date',
    locale: 'en-US',
    dateFormat: {
      year: 'numeric',
      month: '2-digit',
      day: '2-digit'
    }
  }, {
    type: 'intl-date',
    locale: 'de-DE',
    dateFormat: { dateStyle: 'long' }
  }]}
/>

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 (opens new window).

Using string format with Moment.js (deprecated)

Deprecated

The string form of dateFormat (e.g. 'DD/MM/YYYY', 'YYYY-MM-DD') is deprecated and will be removed in the next major release. It is used only by the date cell type, which relies on Moment.js (opens new window) and Pikaday (opens new window). Migrate to the intl-date cell type with an Intl.DateTimeFormat options object.

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:

// Before (deprecated)
columns: [{
  type: 'date',
  dateFormat: 'YYYY-MM-DD',
}]

// After (recommended)
columns: [{
  type: 'intl-date',
  locale: 'en-US',
  dateFormat: {
    year: 'numeric',
    month: '2-digit',
    day: '2-digit',
  }
}]

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.

Cell type