Dates and calendar systems

Date Values

Every date that crosses a component boundary is an ISO YYYY-MM-DD string: value, defaultValue, min, max, month, year, disabledDates, and the cell keys of the pickers. Date-time values use YYYY-MM-DDTHH:mm[:ss].

An ISO day is calendar-neutral. The calendar system only decides how days are grouped into months and years and how they are labeled, so the stored value never changes when the calendar does.

• DayPicker cells are keyed by the day itself.
• MonthPicker cells are keyed by the first day of each month.
• YearPicker cells are keyed by the first day of each year.
• month and year props accept any day inside that month or year.

Install

@vega-ui/react depends on @vega-ui/i18n. Install it directly when the app imports the calendar adapters or helpers, keeping the same version as the one @vega-ui/react uses:

pnpm add @vega-ui/i18n

@vega-ui/i18n has no dependencies and knows nothing about the components: it holds the CalendarSystem type, the Gregorian calendar, ISO day and calendar-aware date helpers, locale and Intl formatting helpers. Typed entry of the date fields builds on it in @vega-ui/utils.

Locale And Calendar Props

Locale and calendar system are root props, like the options of Intl.DateTimeFormat. Calendar, DateField, DateTimeField and DateRangeField, and the low-level DayPicker, MonthPicker and YearPicker, take:

• locale?: string: BCP 47 locale of month and day names and of the first day of the week. Defaults to the locale of the runtime, getDefaultLocale().
• calendar?: CalendarSystem: calendar system months and years are shown in. Defaults to gregorianCalendar.

Every part inside a root (month and year labels, the day grid and its first day of the week, the month and year grids) reads them from the root. The low-level picker layouts also accept their own locale to override it for that layout. Calendar sets lang on its root only when locale is passed.

import { Calendar, CalendarMonthLabel } from '@vega-ui/react';

<Calendar locale='de-DE' defaultValue='2026-03-15'>
  <CalendarMonthLabel />
</Calendar>

getDefaultLocale() returns the runtime locale, new Intl.DateTimeFormat().resolvedOptions().locale. Pass locale explicitly when rendering on the server, so server and client output match.

Other locale helpers take the locales argument of Intl (a tag, an Intl.Locale or a list) and, like Intl, use the runtime locale when it is omitted:

Text Direction

Direction is not derived from locale. Like native elements, Calendar, the pickers, and the calendars of the date fields follow the text direction they are rendered in: dir on <html> or an ancestor, a dir attribute on the component root, or the CSS direction property.

import { Calendar, CalendarDays, CalendarWeekdays, CalendarWeekday, CalendarWeeks, CalendarDay } from '@vega-ui/react';

<div dir='rtl'>
  <Calendar locale='ar-EG'>
    <CalendarDays>
      <CalendarWeekdays>
        <CalendarWeekday />
      </CalendarWeekdays>
      <CalendarWeeks>
        <CalendarDay />
      </CalendarWeeks>
    </CalendarDays>
  </Calendar>
</div>

In a right-to-left context:

• day, month, and year grids run from right to left, so the first day of the week is the rightmost column
• ArrowRight moves to the previous cell and ArrowLeft to the next one; ArrowUp, ArrowDown, Home, and End are unchanged
• the next month or page of years is on the left: swiping to the left and CalendarNextButton show it
• the default chevrons of CalendarPrevButton and CalendarNextButton are mirrored

A calendar rendered in a portal, such as a popover, inherits the direction of the portal container, so set dir on <html> or on the calendar itself.

App-Wide Settings

The library has no global providers. To use the same locale or calendar system everywhere, wrap the component once in the app and use the wrapper instead:

import { Calendar, CalendarProps, CalendarSelection } from '@vega-ui/react';

const appLocale = 'de-DE';

export const AppCalendar = <S extends CalendarSelection = 'single'>(props: CalendarProps<S>) => (
  <Calendar locale={appLocale} {...props} />
);

Props given to the wrapper still win, so a single screen can override the app setting.

Calendar System Adapter

A calendar system is a small adapter object. Two kinds ship with the package, neither with dependencies:

• gregorianCalendar, the shared instance of the GregorianCalendar class, used when no calendar is given. Its methods are bound to the instance, so they can be passed as callbacks, and the class can be extended (see Extending GregorianCalendar);
• createCalendarSystem(identifier), any other calendar built into Intl: 'persian', 'hebrew', 'japanese', 'buddhist', 'roc', 'indian', 'coptic', 'ethiopic', 'islamic-umalqura', 'islamic-civil', 'chinese', 'dangi'… An identifier the runtime does not support throws a RangeError.

import { createCalendarSystem } from '@vega-ui/i18n';

export const persianCalendar = createCalendarSystem('persian');

createCalendarSystem reads the calendar from Intl.DateTimeFormat, so the result is the same as the dates Intl formats:

• months are numbered from the start of the year: 1 to 13 in a Hebrew leap year (Adar I and Adar II included), and a leap month of the Chinese calendar gets its own number;
• eras are the short English era names of Intl, such as 'Reiwa' and 'Heisei'; fields without an era use the current one, so a typed year is a year of the current era;
• a year that ends with an era (Japanese Heisei 31, January 1 to April 30, 2019) has only its own months; fields past its end are clamped to it;
• results are cached per instance, so create each calendar once.

Any other object implementing the CalendarSystem interface works as well:

Month, year, and era names always come from Intl.DateTimeFormat with identifier, so the adapter does not deal with labels.

Create each calendar once, outside of render, and pass it to the root of a component:

const persianCalendar = createCalendarSystem('persian');

<DateField format='yyyy/MM/dd' separator='/' locale='fa-IR' calendar={persianCalendar}>
  <DateFieldInput />
</DateField>

Typing 1405/01/01 is validated against Persian month lengths and resolves to the ISO day 2026-03-21.

Extending GregorianCalendar

A calendar that shares Gregorian months and days can extend GregorianCalendar instead of writing a full adapter. Methods are regular class methods bound in the constructor, so overrides can call super and still be passed as callbacks.

The Thai solar Buddhist calendar (buddhist in Intl) is the Gregorian calendar with years counted from 543 BC:

import { GregorianCalendar, type CalendarDateFields } from '@vega-ui/i18n';

class BuddhistCalendar extends GregorianCalendar {
  readonly identifier = 'buddhist';

  toFields(date: string): CalendarDateFields {
    const fields = super.toFields(date);
    return { ...fields, year: fields.year + 543 };
  }

  fromFields(fields: CalendarDateFields) {
    return super.fromFields({ ...fields, year: fields.year - 543 });
  }

  getDaysInMonth(fields: Pick<CalendarDateFields, 'era' | 'year' | 'month'>) {
    return super.getDaysInMonth({ ...fields, year: fields.year - 543 });
  }
}

export const buddhistCalendar = new BuddhistCalendar();

buddhistCalendar.toFields('2026-02-15') gives { year: 2569, month: 2, day: 15 }, and labels come from Intl with the buddhist identifier (2569 BE). Calendars with their own month lengths, such as Persian or Hebrew, come from createCalendarSystem.

Date Helpers

All helpers take the calendar first and take and return ISO YYYY-MM-DD strings.

Formatting And Parsing

formatCalendarDate(calendar, date, locale, options) formats an ISO day with Intl.DateTimeFormat in a calendar system:

import { formatCalendarDate, gregorianCalendar } from '@vega-ui/i18n';

formatCalendarDate(gregorianCalendar, '2026-03-01', 'en-US', { month: 'short' });

formatCalendarDay(calendar, date, locale, format) formats only the day number, without the suffix some locales add to a standalone day: 15 rather than 15日 in ja-JP.

Creating an Intl.DateTimeFormat is the costly part, so to format many days create one formatter and reuse it. createCalendarDateFormatter(calendar, locale, options) and createCalendarDayFormatter(calendar, locale, format) return (date) => string; the day, month and year grids use them:

import { createCalendarDayFormatter, gregorianCalendar } from '@vega-ui/i18n';

const formatDay = createCalendarDayFormatter(gregorianCalendar, 'ja-JP', 'numeric');
formatDay('2026-03-15'); // '15'

Template helpers implement typed entry in the date fields, so they live in @vega-ui/utils and take the calendar system as their first argument. They read the digits of any numbering system (٠٥.٠١.٢٠٢٦), and the date fields accept them while typing. In a template, dd, mm, and yyyy are calendar day, month, and year, and HH, MM, SS are hours, minutes, and seconds:

• formatTemplateDate(calendar, date, template): ISO value to a typed string
• parseTemplateDate(calendar, value, template): typed string to ISO value, or undefined when incomplete or non-existent
• parseTemplateRange(calendar, value, template, separator): typed range to a [start, end] tuple, '' for an incomplete bound
• normalizeTemplateDate(calendar, value, template, { min, max }): pads a single digit that cannot start a two-digit segment, clamps complete segments to the calendar, and clamps a complete value to min / max
• stepTimeSegment(value, template, position, direction, step): steps the time segment under the caret; time does not depend on the calendar, so it takes none

Common Mistakes

• Passing Date objects, timestamps, numeric years, or zero-based months instead of ISO strings.
• Converting values to the display calendar before storing them; store the ISO day and let the calendar format it.
• Creating a new adapter on every render.
• Giving a picker and its surrounding field different calendar values.