Choose a calendar

Use this page after your first picker when you need Gregorian, Jalali/Persian, Hijri, or Thai Buddhist dates. Import one exported adapter and pass it to a component; then use locale for language, digits, and direction.

Calix keeps calendar behavior behind CalendarAdapter. Components never need to know how a month rolls over, which digits a locale uses, or how to parse a date—those are adapter responsibilities.

At the React boundary, values are JavaScript Date objects. Within the core, an adapter works with calendar-neutral parts:

interface CalendarDate {
  year: number;
  month: number; // 1-based
  day: number; // 1-based
}

Built-in adapters

import { gregorian } from "@alydev/adapter-gregorian";
import { jalali } from "@alydev/adapter-jalali";
import { hijri } from "@alydev/adapter-hijri";
import { buddhist } from "@alydev/adapter-buddhist";
 
<DatePicker adapter={gregorian} locale="en-US" />;
<DatePicker adapter={jalali} locale="fa-IR" dir="rtl" />;
<DatePicker adapter={hijri} locale="ar-SA" dir="rtl" />;
<DatePicker adapter={buddhist} locale="th-TH" />;

All four are stateless singletons. Reuse the exported adapter everywhere; locale is always passed to the component rather than stored on the adapter. One Gregorian adapter can therefore serve en-US, en-GB, and fr-FR at the same time.

The Hijri adapter uses the platform ICU islamic-umalqura calendar, so it ships without date tables. The Thai Buddhist adapter uses Gregorian month/day rules and represents years in Buddhist Era (BE = CE + 543).

For week starts, custom labels, RTL, and runtime locale changes, continue to Localization. Only implement a custom adapter when none of these built-ins fits your calendar system.

Adapter responsibilities

Implement a custom adapter when the bundled calendars do not cover your system. CalendarAdapter includes:

• conversion between CalendarDate and local JavaScript Date;
• arithmetic (addDays, addMonths, addYears) and month boundaries;
• month-grid and week-number support;
• comparison and equality;
• localized month, weekday, and era names;
• parsing, formatting, and RTL detection.

The @alydev/core helpers can do the generic parts:

import { generateMonthGrid, type CalendarAdapter } from "@alydev/core";
 
export const myCalendar: CalendarAdapter = {
  id: "my-calendar",
  defaultLocale: "en-US",
  // Implement conversion, arithmetic, names, formatting, parsing, and comparisons.
  getMonthGrid: (view, options) => generateMonthGrid(myCalendar, view, options),
};

Use CalendarAdapter in the API reference as the definitive method list. The repository's adapter architecture explains the design decisions.

Time zones

Calix uses local JavaScript Date conversion at its public boundary. It is a date/time picker, not a time-zone conversion library. If your application stores instants in UTC, convert at your application boundary and keep the calendar's selected local date separate from server serialization.