Skip to content
Handsontable dev

Date cell type

Display, format, sort, and filter dates correctly by using the date cell type.

The date cell type provides a date picker for selecting and displaying dates. It validates input against a configurable date format.

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. Use the intl-date or date cell type with the native Intl.DateTimeFormat API and ISO 8601 date strings.

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
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 = [
  {
    car: 'Mercedes A 160',
    product_date: '2002-06-15',
    payment_date: '2002-05-20',
    registration_date: '2002-07-01',
  },
  {
    car: 'Citroën C4 Coupe',
    product_date: '2007-03-22',
    payment_date: '2007-02-28',
    registration_date: '2007-04-10',
  },
  {
    car: 'Audi A4 Avant',
    product_date: '2011-09-08',
    payment_date: '2011-08-15',
    registration_date: '2011-09-20',
  },
  {
    car: 'Opel Astra',
    product_date: '2012-01-30',
    payment_date: '2012-01-10',
    registration_date: '2012-02-14',
  },
  {
    car: 'BMW 320i Coupe',
    product_date: '2004-11-12',
    payment_date: '2004-10-20',
    registration_date: '2004-12-01',
  },
];


const hotSettings = ref<GridSettings>({
  data,
  colHeaders: ['Car', 'Product date', 'Payment date', 'Registration date'],
  locale: 'en-US',
  columns: [
    {
      type: 'text',
      data: 'car',
    },
    {
      type: 'intl-date',
      data: 'product_date',
      dateFormat: { dateStyle: 'short' },
    },
    {
      type: 'intl-date',
      data: 'payment_date',
      dateFormat: {
        month: 'long',
        day: 'numeric',
        year: 'numeric',
      },
    },
    {
      type: 'intl-date',
      data: 'registration_date',
      dateFormat: {
        weekday: 'long',
        year: 'numeric',
        month: 'long',
        day: 'numeric',
      },
    },
  ],
  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 date cell type

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

// set the date cell type for the entire grid (Intl, recommended)
const hotSettings = ref({
  type: 'intl-date',
  locale: 'en-US',
  dateFormat: {
    year: 'numeric',
    month: '2-digit',
    day: '2-digit'
  }
});


// set the date cell type for a single column
const hotSettings = ref({
  columns: [
    {
      type: 'intl-date',
      locale: 'en-US',
      dateFormat: { dateStyle: 'short' }
    }
  ]
});


// set the date cell type for a single cell
const hotSettings = ref({
  cell: [
    {
      row: 0,
      col: 2,
      type: 'intl-date',
      locale: 'en-US',
      dateFormat: { dateStyle: 'medium' }
    }
  ]
});

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

Using Intl.DateTimeFormat

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

const hotSettings = ref({
  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:

PropertyPossible valuesDescription
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:

PropertyPossible valuesDescription
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
fractionalSecondDigits1, 2, 3Fraction-of-second digits
timeZoneName'long', 'short', 'shortOffset', 'longOffset', 'shortGeneric', 'longGeneric'Time zone display

Locale and other options:

PropertyPossible valuesDescription
localeMatcher'best fit' (default), 'lookup'Locale matching algorithm
calendar'chinese', 'gregory', 'persian', etc.Calendar to use
numberingSystem'latn', 'arab', 'hans', etc.Numbering system
timeZoneIANA time zone (e.g. 'UTC', 'America/New_York')Time zone for formatting
hour12true, false12-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.

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 and date, the underlying value remains in ISO 8601 format.

Result

After configuring the date cell type, cells display dates formatted according to your dateFormat configuration. Clicking an intl-date or date cell opens a native date picker. Source data is stored in ISO 8601 format (YYYY-MM-DD) regardless of the display format.

Related guides

Cell type

Configuration options

dateFormat
locale
type
defaultDate
valueFormatter
valueParser
valueSetter
valueGetter

Core methods

getCellMeta()
getCellMetaAtRow()
getCellsMeta()
getDataType()
setCellMeta()
setCellMetaObject()
removeCellMeta()

Hooks

afterGetCellMeta
afterSetCellMeta
beforeGetCellMeta
beforeSetCellMeta