JavaScript Data GridDate cell type
Display, format, sort, and filter dates correctly by using the date cell type.
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
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'.
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.
Related articles
Related guides
Related API reference
- Configuration options:
- Core methods:
- Hooks: