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

Source code

TypeScript

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

interface ShiftData {
  shift: string;
  start: string;
  breakStart: string;
  end: string;
}

@Component({
  selector: 'example1-time-cell-type',
  standalone: false,
  template: `
    <div class="example-controls-container">
      <div class="controls">
        <div class="theme-dropdown" #dropdownRef>
          <button
            class="theme-dropdown-trigger"
            type="button"
            aria-haspopup="listbox"
            [attr.aria-expanded]="isOpen"
            (click)="toggleDropdown()"
          >
            <span>{{ selectedLabel }}</span>
            <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>
          </button>
          <ul class="theme-dropdown-menu" role="listbox" *ngIf="isOpen">
            <li
              *ngFor="let opt of localeOptions"
              role="option"
              [attr.aria-selected]="locale === opt.value"
              (click)="selectLocale(opt.value)"
            >
              {{ opt.label }}
            </li>
          </ul>
        </div>
      </div>
    </div>
    <div>
      <hot-table [data]="data" [settings]="gridSettings"></hot-table>
    </div>
  `,
  encapsulation: ViewEncapsulation.None
})
export class Example1TimeCellTypeComponent {
  @ViewChild(HotTableComponent, { static: false }) readonly hotTable!: HotTableComponent;

  isOpen = false;
  locale = 'en-US';

  readonly localeOptions = [
    { value: 'ar-AR', label: 'Arabic (Global)' },
    { value: 'cs-CZ', label: 'Czech (Czechia)' },
    { value: 'de-CH', label: 'German (Switzerland)' },
    { value: 'de-DE', label: 'German (Germany)' },
    { value: 'en-US', label: 'English (United States)' },
    { value: 'es-MX', label: 'Spanish (Mexico)' },
    { value: 'fa-IR', label: 'Persian (Iran)' },
    { value: 'fr-FR', label: 'French (France)' },
    { value: 'hr-HR', label: 'Croatian (Croatia)' },
    { value: 'it-IT', label: 'Italian (Italy)' },
    { value: 'ja-JP', label: 'Japanese (Japan)' },
    { value: 'ko-KR', label: 'Korean (Korea)' },
    { value: 'lv-LV', label: 'Latvian (Latvia)' },
    { value: 'nb-NO', label: 'Norwegian Bokmal (Norway)' },
    { value: 'nl-NL', label: 'Dutch (Netherlands)' },
    { value: 'pl-PL', label: 'Polish (Poland)' },
    { value: 'pt-BR', label: 'Portuguese (Brazil)' },
    { value: 'ru-RU', label: 'Russian (Russia)' },
    { value: 'sr-SP', label: 'Serbian Latin (Serbia)' },
    { value: 'zh-CN', label: 'Chinese (Simplified, China)' },
    { value: 'zh-TW', label: 'Chinese (Traditional, Taiwan)' },
  ];

  readonly data: ShiftData[] = [
    { shift: 'Morning', start: '09:00', breakStart: '12:00', end: '17:00' },
    { shift: 'Afternoon', start: '13:30', breakStart: '16:00', end: '21:00' },
    { shift: 'Night', start: '22:00', breakStart: '01:00', end: '06:00' },
    { shift: 'Split', start: '08:00', breakStart: '12:30', end: '20:00' },
    { shift: 'Short day', start: '10:00', breakStart: '13:00', end: '15:00' },
  ];

  readonly gridSettings: GridSettings = {
    colHeaders: ['Shift', 'Start', 'Break start', 'End'],
    locale: this.locale,
    columns: [
      {
        type: 'text',
        data: 'shift',
      },
      {
        type: 'intl-time',
        data: 'start',
        timeFormat: {
          timeStyle: 'short',
        },
      },
      {
        type: 'intl-time',
        data: 'breakStart',
        timeFormat: {
          hour: '2-digit',
          minute: '2-digit',
          second: '2-digit',
        },
      },
      {
        type: 'intl-time',
        data: 'end',
        timeFormat: {
          hour: 'numeric',
          hourCycle: 'h12',
          dayPeriod: 'short',
        },
      },
    ],
    columnSorting: true,
    filters: true,
    dropdownMenu: true,
    height: 'auto',
    autoWrapRow: true,
    autoWrapCol: true,
  };

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

  constructor(private elementRef: ElementRef) {}

  toggleDropdown(): void {
    this.isOpen = !this.isOpen;
  }

  selectLocale(value: string): void {
    this.locale = value;
    this.isOpen = false;
    this.hotTable?.hotInstance?.updateSettings({ locale: this.locale });
  }

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

  @HostListener('document:keydown', ['$event'])
  onKeydown(event: KeyboardEvent): void {
    if (event.key === 'Escape') {
      this.isOpen = false;
    }
  }
}
/* end-file */


/* file: app.module.ts */
import { NgModule, ApplicationConfig } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { registerAllModules } from 'handsontable/registry';
import { HOT_GLOBAL_CONFIG, HotGlobalConfig, HotTableModule } from '@handsontable/angular-wrapper';
import { CommonModule } from '@angular/common';
import { NON_COMMERCIAL_LICENSE } from '@handsontable/angular-wrapper';
/* start:skip-in-compilation */
import { Example1TimeCellTypeComponent } from './app.component';
/* end:skip-in-compilation */

// register Handsontable's modules
registerAllModules();

export const appConfig: ApplicationConfig = {
  providers: [
    {
      provide: HOT_GLOBAL_CONFIG,
      useValue: {
        license: NON_COMMERCIAL_LICENSE,
      } as HotGlobalConfig
    }
  ],
};

@NgModule({
  imports: [ BrowserModule, HotTableModule, CommonModule ],
  declarations: [ Example1TimeCellTypeComponent ],
  providers: [...appConfig.providers],
  bootstrap: [ Example1TimeCellTypeComponent ]
})

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

HTML

<div>
  <example1-time-cell-type></example1-time-cell-type>
</div>

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

Using Intl.DateTimeFormat (recommended)

The timeFormat option accepts properties of Intl.DateTimeFormat options 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.

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. 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

Cell type→

Configuration options

timeFormat→

locale→

type→

correctFormat→

valueFormatter→

valueParser→

valueSetter→

valueGetter→

Core methods

getCellMeta()→

getCellMetaAtRow()→

getCellsMeta()→

getDataType()→

setCellMeta()→

setCellMetaObject()→

removeCellMeta()→

Hooks

afterGetCellMeta→

afterSetCellMeta→

beforeGetCellMeta→

beforeSetCellMeta→