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

1
/* file: app.component.ts */
2
import { Component, ViewChild, ViewEncapsulation, HostListener, ElementRef } from '@angular/core';
3
import { GridSettings, HotTableComponent } from '@handsontable/angular-wrapper';
4

5
interface CarData {
6
  car: string;
7
  product_date: string;
8
  payment_date: string;
9
  registration_date: string;
10
}
11

12
@Component({
13
  selector: 'example1-date-cell-type',
14
  standalone: false,
15
  template: `
16
    <div class="example-controls-container">
17
      <div class="controls">
18
        <div class="theme-dropdown" #dropdownRef>
19
          <button
20
            class="theme-dropdown-trigger"
21
            type="button"
22
            aria-haspopup="listbox"
23
            [attr.aria-expanded]="isOpen"
24
            (click)="toggleDropdown()"
25
          >
26
            <span>{{ selectedLabel }}</span>
27
            <svg class="theme-dropdown-chevron" aria-hidden="true" width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M6 9l6 6l6 -6"/></svg>
28
          </button>
29
          <ul class="theme-dropdown-menu" role="listbox" *ngIf="isOpen">
30
            <li
31
              *ngFor="let opt of localeOptions"
32
              role="option"
33
              [attr.aria-selected]="locale === opt.value"
34
              (click)="selectLocale(opt.value)"
35
            >
36
              {{ opt.label }}
37
            </li>
38
          </ul>
39
        </div>
40
      </div>
41
    </div>
42
    <div>
43
      <hot-table [data]="data" [settings]="gridSettings"></hot-table>
44
    </div>
45
  `,
46
  encapsulation: ViewEncapsulation.None
47
})
48
export class Example1DateCellTypeComponent {
49
  @ViewChild(HotTableComponent, { static: false }) readonly hotTable!: HotTableComponent;
50

51
  isOpen = false;
52
  locale = 'en-US';
53

56 collapsed lines
54
  readonly localeOptions = [
55
    { value: 'ar-AR', label: 'Arabic (Global)' },
56
    { value: 'cs-CZ', label: 'Czech (Czechia)' },
57
    { value: 'de-CH', label: 'German (Switzerland)' },
58
    { value: 'de-DE', label: 'German (Germany)' },
59
    { value: 'en-US', label: 'English (United States)' },
60
    { value: 'es-MX', label: 'Spanish (Mexico)' },
61
    { value: 'fa-IR', label: 'Persian (Iran)' },
62
    { value: 'fr-FR', label: 'French (France)' },
63
    { value: 'hr-HR', label: 'Croatian (Croatia)' },
64
    { value: 'it-IT', label: 'Italian (Italy)' },
65
    { value: 'ja-JP', label: 'Japanese (Japan)' },
66
    { value: 'ko-KR', label: 'Korean (Korea)' },
67
    { value: 'lv-LV', label: 'Latvian (Latvia)' },
68
    { value: 'nb-NO', label: 'Norwegian Bokmal (Norway)' },
69
    { value: 'nl-NL', label: 'Dutch (Netherlands)' },
70
    { value: 'pl-PL', label: 'Polish (Poland)' },
71
    { value: 'pt-BR', label: 'Portuguese (Brazil)' },
72
    { value: 'ru-RU', label: 'Russian (Russia)' },
73
    { value: 'sr-SP', label: 'Serbian Latin (Serbia)' },
74
    { value: 'zh-CN', label: 'Chinese (Simplified, China)' },
75
    { value: 'zh-TW', label: 'Chinese (Traditional, Taiwan)' },
76
  ];
77

78
  readonly data: CarData[] = [
79
    {
80
      car: 'Mercedes A 160',
81
      product_date: '2002-06-15',
82
      payment_date: '2002-05-20',
83
      registration_date: '2002-07-01',
84
    },
85
    {
86
      car: 'Citroën C4 Coupe',
87
      product_date: '2007-03-22',
88
      payment_date: '2007-02-28',
89
      registration_date: '2007-04-10',
90
    },
91
    {
92
      car: 'Audi A4 Avant',
93
      product_date: '2011-09-08',
94
      payment_date: '2011-08-15',
95
      registration_date: '2011-09-20',
96
    },
97
    {
98
      car: 'Opel Astra',
99
      product_date: '2012-01-30',
100
      payment_date: '2012-01-10',
101
      registration_date: '2012-02-14',
102
    },
103
    {
104
      car: 'BMW 320i Coupe',
105
      product_date: '2004-11-12',
106
      payment_date: '2004-10-20',
107
      registration_date: '2004-12-01',
108
    },
109
  ];
110

111
  readonly gridSettings: GridSettings = {
112
    colHeaders: ['Car', 'Product date', 'Payment date', 'Registration date'],
113
    locale: this.locale,
36 collapsed lines
114
    columns: [
115
      {
116
        type: 'text',
117
        data: 'car',
118
      },
119
      {
120
        type: 'intl-date',
121
        data: 'product_date',
122
        dateFormat: { dateStyle: 'short' },
123
      },
124
      {
125
        type: 'intl-date',
126
        data: 'payment_date',
127
        dateFormat: {
128
          month: 'long',
129
          day: 'numeric',
130
          year: 'numeric',
131
        },
132
      },
133
      {
134
        type: 'intl-date',
135
        data: 'registration_date',
136
        dateFormat: {
137
          weekday: 'long',
138
          year: 'numeric',
139
          month: 'long',
140
          day: 'numeric',
141
        },
142
      },
143
    ],
144
    columnSorting: true,
145
    filters: true,
146
    dropdownMenu: true,
147
    height: 'auto',
148
    autoWrapRow: true,
149
    autoWrapCol: true,
150
  };
151

152
  get selectedLabel(): string {
153
    return this.localeOptions.find((o) => o.value === this.locale)?.label || '';
154
  }
155

156
  constructor(private elementRef: ElementRef) {}
157

158
  toggleDropdown(): void {
159
    this.isOpen = !this.isOpen;
160
  }
161

162
  selectLocale(value: string): void {
163
    this.locale = value;
164
    this.isOpen = false;
165
    this.hotTable?.hotInstance?.updateSettings({ locale: this.locale });
166
  }
167

168
  @HostListener('document:click', ['$event'])
169
  onDocumentClick(event: MouseEvent): void {
170
    if (!this.elementRef.nativeElement.querySelector('.theme-dropdown')?.contains(event.target)) {
171
      this.isOpen = false;
172
    }
173
  }
174

175
  @HostListener('document:keydown', ['$event'])
176
  onKeydown(event: KeyboardEvent): void {
177
    if (event.key === 'Escape') {
178
      this.isOpen = false;
179
    }
180
  }
181
}
182
/* end-file */
183

184

185
/* file: app.module.ts */
186
import { NgModule, ApplicationConfig } from '@angular/core';
187
import { BrowserModule } from '@angular/platform-browser';
188
import { registerAllModules } from 'handsontable/registry';
189
import { HOT_GLOBAL_CONFIG, HotGlobalConfig, HotTableModule } from '@handsontable/angular-wrapper';
190
import { CommonModule } from '@angular/common';
191
import { NON_COMMERCIAL_LICENSE } from '@handsontable/angular-wrapper';
192
/* start:skip-in-compilation */
193
import { Example1DateCellTypeComponent } from './app.component';
194
/* end:skip-in-compilation */
195

196
// register Handsontable's modules
197
registerAllModules();
198

199
export const appConfig: ApplicationConfig = {
200
  providers: [
201
    {
202
      provide: HOT_GLOBAL_CONFIG,
203
      useValue: {
204
        license: NON_COMMERCIAL_LICENSE,
205
      } as HotGlobalConfig
206
    }
207
  ],
208
};
209

210
@NgModule({
211
  imports: [ BrowserModule, HotTableModule, CommonModule ],
212
  declarations: [ Example1DateCellTypeComponent ],
213
  providers: [...appConfig.providers],
214
  bootstrap: [ Example1DateCellTypeComponent ]
215
})
216

217
export class AppModule { }
218
/* end-file */

1
<div>
2
  <example1-date-cell-type></example1-date-cell-type>
3
</div>

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.

1
// set the date cell type for the entire grid (Intl, recommended)
2
settings1 = {
3
  type: 'intl-date',
4
  locale: 'en-US',
5
  dateFormat: {
6
    year: 'numeric',
7
    month: '2-digit',
8
    day: '2-digit'
9
  }
10
};
11

12
// set the date cell type for a single column
13
settings2 = {
14
  columns: [
15
    {
16
      type: 'intl-date',
17
      locale: 'en-US',
18
      dateFormat: { dateStyle: 'short' }
19
    }
20
  ]
21
};
22

23
// set the date cell type for a single cell
24
settings3 = {
25
  cell: [
26
    {
27
      row: 0,
28
      col: 2,
29
      type: 'intl-date',
30
      locale: 'en-US',
31
      dateFormat: { dateStyle: 'medium' }
32
    }
33
  ]
34
};

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 API. The locale is controlled separately via the locale option.

Using Intl.DateTimeFormat (recommended)

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

1
settings = {
2
  columns: [
3
    {
4
      type: 'intl-date',
5
      locale: 'en-US',
6
      dateFormat: {
7
        year: 'numeric',
8
        month: '2-digit',
9
        day: '2-digit'
10
      }
11
    },
12
    {
13
      type: 'intl-date',
14
      locale: 'de-DE',
15
      dateFormat: { dateStyle: 'long' }
16
    }
17
  ]
18
};

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.

Using string format with Moment.js (deprecated)

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:

1
// Before (deprecated)
2
columns: [{
3
  type: 'date',
4
  dateFormat: 'YYYY-MM-DD',
5
}]
6

7
// After (recommended)
8
columns: [{
9
  type: 'intl-date',
10
  locale: 'en-US',
11
  dateFormat: {
12
    year: 'numeric',
13
    month: '2-digit',
14
    day: '2-digit',
15
  }
16
}]

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 guides

Cell type

Configuration options

Core methods

Hooks