Angular Data GridTime cell type
Display, format, sort, and filter time values correctly by using the time cell type. Edit times via the cell editor.
Overview
The time cell type lets you treat cell values as times: format how they are displayed and validate input. 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).
Time cell type demo
In the following demo, the Start, Break start, and End columns use the time cell type with different formats: short style, custom format with hours, minutes, and seconds, and format with day period. Use the locale selector to see how each format varies by locale.
Use the time cell type
Use the object-style configuration by setting the type option to 'intl-time' and timeFormat to an object (recommended). The locale is controlled via the locale option.
// set the time cell type for the entire grid (Intl, recommended)
settings1 = {
type: 'intl-time',
locale: 'en-US',
timeFormat: {
hour: 'numeric',
minute: '2-digit',
second: '2-digit',
hour12: true
}
};
// set the time cell type for a single column
settings2 = {
columns: [
{
type: 'intl-time',
locale: 'en-US',
timeFormat: { timeStyle: 'medium' }
}
]
};
// set the time cell type for a single cell
settings3 = {
cell: [
{
row: 0,
col: 2,
type: 'intl-time',
locale: 'en-US',
timeFormat: { hour: '2-digit', minute: '2-digit', hour12: true }
}
]
};
For intl-time cells, source data must be in 24-hour time format (HH:mm, HH:mm:ss, or HH:mm:ss.SSS) for times to work correctly. The timeFormat object only affects how times are displayed; sorting and filtering rely on the underlying value.
Format times
To control how times are displayed in cell renderers, use the timeFormat option.
Since Handsontable 17.0, the recommended approach is the object form of timeFormat with the intl-time 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 timeFormat option accepts properties of Intl.DateTimeFormat options (opens new window) relevant to time. Use it with type: 'intl-time'.
settings = {
columns: [
{
type: 'intl-time',
locale: 'en-US',
timeFormat: {
hour: 'numeric',
minute: '2-digit',
second: '2-digit',
hour12: true
}
},
{
type: 'intl-time',
locale: 'de-DE',
timeFormat: { timeStyle: 'medium' }
}
]
};
Time-specific options
Style shortcuts:
| Property | Possible values | Description |
|---|---|---|
timeStyle | 'full', 'long', 'medium', 'short' | Time formatting style (hour, minute, second, timeZoneName) |
Time component options:
| Property | Possible values | Description |
|---|---|---|
hour | 'numeric', '2-digit' | Hour representation |
minute | 'numeric', '2-digit' | Minute representation |
second | 'numeric', '2-digit' | Second representation |
fractionalSecondDigits | 1, 2, 3 | Fraction-of-second digits |
dayPeriod | 'narrow', 'short', 'long' | Day period (e.g. "am") |
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 |
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 timeFormat API documentation or MDN: Intl.DateTimeFormat (opens new window).
Using string format with Moment.js (deprecated)
Deprecated
The string form of timeFormat (e.g. 'h:mm:ss a') is deprecated and will be removed in the next major release. It is used only by the time cell type, which relies on Moment.js (opens new window). Migrate to the intl-time cell type with an Intl.DateTimeFormat options object.
The time cell type with a string timeFormat is still supported but will be removed in next major release.
Deprecated options:
| Option | Description | Replacement |
|---|---|---|
timeFormat (string) | Moment.js format (e.g. 'h:mm:ss a') | Use intl-time with timeFormat object (see above) |
correctFormat | Auto-correct entered time to match format | May be handled by valueParser and/or valueSetter options |
Migration example:
// Before (deprecated)
columns: [{
type: 'time',
timeFormat: 'h:mm:ss a',
}]
// After (recommended)
columns: [{
type: 'intl-time',
locale: 'en-US',
timeFormat: {
hour: 'numeric',
minute: '2-digit',
second: '2-digit',
hour12: true,
}
}]
Editor behavior
The timeFormat option controls how times are displayed in the cell. The editor may show the value in a normalized form; for intl-time, the underlying value remains in 24-hour format (HH:mm, HH:mm:ss, or HH:mm:ss.SSS).
Related articles
Related guides
Related API reference
- Configuration options:
- Core methods:
- Hooks: