Time cell type

Display, format, sort, and filter time values correctly by using the time cell type. Edit times via the cell editor.

The time cell type formats time values using a configurable format string. Use it for scheduling, logging, or any time-based data.

Overview

The time cell type lets you treat cell values as times: format how they are displayed and validate input. Use the intl-time or time cell type with the native Intl.DateTimeFormat API and 24-hour time strings.

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

Vue

<script setup lang="ts">
import { ref, onMounted, onBeforeUnmount, useTemplateRef } from 'vue';
import { HotTable } from '@handsontable/vue3';
import { registerAllModules } from 'handsontable/registry';
import type { GridSettings } from 'handsontable/settings';

// register Handsontable's modules
registerAllModules();

const 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)' },
];

const hotRef = useTemplateRef<InstanceType<typeof HotTable>>('hotRef');
const dropdownRef = useTemplateRef<HTMLDivElement>('dropdownRef');
const isOpen = ref(false);
const locale = ref('en-US');

const selectedLabel = () => localeOptions.find((o) => o.value === locale.value)?.label;

const handleSelect = (value: string) => {
  locale.value = value;
  isOpen.value = false;
  hotRef.value?.hotInstance?.updateSettings({ locale: value } as GridSettings);
};

const handleOutsideClick = (e: MouseEvent) => {
  if (dropdownRef.value && !dropdownRef.value.contains(e.target as Node)) {
    isOpen.value = false;
  }
};

const handleEscape = (e: KeyboardEvent) => {
  if (e.key === 'Escape') {
    isOpen.value = false;
  }
};

onMounted(() => {
  document.addEventListener('click', handleOutsideClick);
  document.addEventListener('keydown', handleEscape);
});

onBeforeUnmount(() => {
  document.removeEventListener('click', handleOutsideClick);
  document.removeEventListener('keydown', handleEscape);
});

const data = [
  { 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' },
];

const hotSettings = ref<GridSettings>({
  data,
  colHeaders: ['Shift', 'Start', 'Break start', 'End'],
  locale: 'en-US',
  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,
  licenseKey: 'non-commercial-and-evaluation',
});
</script>

<template>
  <div id="example1">
    <div class="example-controls-container">
      <div class="controls">
        <div class="theme-dropdown" ref="dropdownRef">
          <button
            class="theme-dropdown-trigger"
            type="button"
            aria-haspopup="listbox"
            :aria-expanded="isOpen"
            @click="isOpen = !isOpen"
          >
            <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 v-if="isOpen" class="theme-dropdown-menu" role="listbox">
            <li
              v-for="opt in localeOptions"
              :key="opt.value"
              role="option"
              :aria-selected="locale === opt.value"
              @click="handleSelect(opt.value)"
            >
              {{ opt.label }}
            </li>
          </ul>
        </div>
      </div>
    </div>
    <HotTable ref="hotRef" :settings="hotSettings" />
  </div>
</template>

Use the time cell type

Use the object-style configuration by setting the type option to 'intl-time' or 'time' and timeFormat to an object. The locale is controlled via the locale option.

<script setup lang="ts">
import { ref } from 'vue';
import { HotTable } from '@handsontable/vue3';
import { registerAllModules } from 'handsontable/registry';
import type { GridSettings } from 'handsontable/settings';

registerAllModules();

// set the time cell type for the entire grid (Intl, recommended)
const hotSettings = ref<GridSettings>({
  type: 'intl-time',
  locale: 'en-US',
  timeFormat: {
    hour: 'numeric',
    minute: '2-digit',
    second: '2-digit',
    hour12: true
  },
  licenseKey: 'non-commercial-and-evaluation',
});

// set the time cell type for a single column
const hotSettingsColumn = ref<GridSettings>({
  columns: [
    {
      type: 'intl-time',
      locale: 'en-US',
      timeFormat: { timeStyle: 'medium' }
    }
  ],
  licenseKey: 'non-commercial-and-evaluation',
});

// set the time cell type for a single cell
const hotSettingsCell = ref<GridSettings>({
  cell: [
    {
      row: 0,
      col: 2,
      type: 'intl-time',
      locale: 'en-US',
      timeFormat: { hour: '2-digit', minute: '2-digit', hour12: true }
    }
  ],
  licenseKey: 'non-commercial-and-evaluation',
});
</script>

For intl-time and 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 18.0, the object form of timeFormat with the intl-time and time cell types is required. It uses the native Intl.DateTimeFormat API. The locale is controlled separately via the locale option.

Using Intl.DateTimeFormat

The timeFormat option accepts properties of Intl.DateTimeFormat options relevant to time. Use it with type: 'intl-time' or type: 'time'.

<script setup lang="ts">
import { ref } from 'vue';
import { HotTable } from '@handsontable/vue3';
import { registerAllModules } from 'handsontable/registry';
import type { GridSettings } from 'handsontable/settings';

registerAllModules();

const hotSettings = ref<GridSettings>({
  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' }
    }
  ],
  licenseKey: 'non-commercial-and-evaluation',
});
</script>

<template>
  <HotTable :settings="hotSettings" />
</template>

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.

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 and time, the underlying value remains in 24-hour format (HH:mm, HH:mm:ss, or HH:mm:ss.SSS).

Result

After configuring the time cell type, cells display time values formatted according to your timeFormat configuration. Clicking an intl-time or time cell opens a native time picker. Source data is stored in 24-hour format (HH:mm, HH:mm:ss, or HH:mm:ss.SSS) regardless of the display format.

Related articles

Related guides

Cell type→

Configuration options

timeFormat→

locale→

type→

valueFormatter→

valueParser→

valueSetter→

valueGetter→

Core methods

getCellMeta()→

getCellMetaAtRow()→

getCellsMeta()→

getDataType()→

setCellMeta()→

setCellMetaObject()→

removeCellMeta()→

Hooks

afterGetCellMeta→

afterSetCellMeta→

beforeGetCellMeta→

beforeSetCellMeta→