modo-calendar

ModoCalendar

A modern, zero-dependency date picker for the web. TypeScript-first, plugin-based, Shadow DOM encapsulated.

Supports single, range, and multiple date selection with advanced features like time slots, date/time blocking rules, multi-month views, preset ranges, dropdowns, and i18n — all through a clean plugin architecture.

Features

• Three selection modes — single, range (with min/max nights), multiple (with max count)
• Plugin system — compose only what you need: months, time, lock, presets, dropdown, i18n
• Lock rules engine — flexible date & time blocking: individual dates, ranges, recurring weekdays, combined filters, checkin/checkout restrictions, time slot blocking
• Time selection — block grid or spinner picker, per-date time slots, lock-rules integration
• Shadow DOM — styles fully encapsulated, no CSS conflicts
• Reactive state — Proxy-based auto-sync, batch updates
• Animations & gestures — swipe navigation, staggered fade-in, selection animations
• Keyboard navigation — full arrow-key, Enter, Escape support
• i18n — locale-aware formatting, runtime locale switching
• CSS custom properties — fully themeable via --mc-* variables
• BEM class overrides — classNames API for custom styling slots
• Accessible — WCAG 2.1 compliant: aria-modal, focus trap, aria-disabled on blocked days, keyboard-navigable spinners
• Zero dependencies — ~25 kB gzipped (ESM)

Installation

npm install modo-calendar

Quick Start

import { ModoCalendar } from 'modo-calendar';

new ModoCalendar({
  trigger: '#datepicker',
  mode: 'single',
});

Modes

Single date

new ModoCalendar({
  trigger: '#picker',
  mode: 'single',
});

Date range

import { ModoCalendar, monthsPlugin } from 'modo-calendar';

new ModoCalendar({
  trigger: '#picker',
  mode: 'range',
  minRangeNights: 2,
  maxRangeNights: 14,
  plugins: [monthsPlugin({ months: 2 })],
});

Multiple dates

new ModoCalendar({
  trigger: '#picker',
  mode: 'multiple',
  maxMultipleDates: 5,
});

Plugins

monthsPlugin

Display multiple months side by side.

import { monthsPlugin } from 'modo-calendar';

monthsPlugin({ months: 2 });

timePlugin

Add time slot selection (block grid or spinner).

import { timePlugin } from 'modo-calendar';

// Block grid: 90-minute slots from 08:00 to 18:00
timePlugin({
  from: '08:00',
  to: '18:00',
  interval: 90,
  pickerType: 'blocks', // default
});

// Spinner: hour/minute wheels with 15-min steps
timePlugin({
  pickerType: 'spinner',
  minuteStep: 15,
});

// Multiple dates with arrival/departure per date
timePlugin({
  arrivalDeparture: true,
  pickerType: 'blocks',
  from: '08:00',
  to: '18:00',
  interval: 60,
});

// Time-only (calendar grid hidden, fixed date)
timePlugin({
  hideCalendar: true,
  date: '2026-04-20',
  from: '09:00',
  to: '17:00',
  interval: 30,
});

Option	Type	Default	Description
from	string	'08:00'	Start time (HH:MM)
to	string	'16:00'	End time (HH:MM)
interval	number	60	Block duration in minutes
pickerType	'blocks' | 'spinner'	'blocks'	Picker UI type
minuteStep	number	5	Minute increment for spinner
disabledTimes	string[]	[]	Statically disabled time labels
isTimeBlocked	(time, dates) => boolean	—	Custom blocking callback
arrivalDeparture	boolean	false	Show arrival + departure pickers per date (multiple mode)
hideCalendar	boolean	false	Hide the calendar grid + header to render only the time picker. Requires date.
date	string | Date	—	Fixed date for time-only flows. "YYYY-MM-DD" string or Date. Required with hideCalendar.

Arrival / Departure in multiple mode

When arrivalDeparture: true is combined with mode: 'multiple', each selected date shows two time pickers (arrival and departure) instead of one. The hidden input outputs per-date time pairs:

{
  "mode": "multiple",
  "dates": [1713139200000, 1713225600000],
  "timePairs": {
    "1713139200000": {
      "arrival": "09:00 - 10:00",
      "departure": "16:00 - 17:00"
    },
    "1713225600000": { "arrival": null, "departure": null }
  }
}

Chips and button labels display the format: 15 avr. (09:00 → 17:00).

In range mode, arrival/departure already works by default (no option needed) — the start date gets the arrival picker and the end date gets the departure picker.

lockPlugin

Flexible date & time blocking with a rules engine. Rules are evaluated in order and effects accumulate.

import { lockPlugin } from 'modo-calendar';

lockPlugin({
  rules: [
    // Block specific dates
    { dates: ['2026-04-20', '2026-04-24'], blocked: true },

    // Block every Sunday
    { weekdays: ['sun'], blocked: true },

    // Block Tuesdays only in April 2026
    { from: '2026-04-01', to: '2026-04-30', weekdays: ['tue'], blocked: true },

    // Allow booking over, but no check-in
    { dates: ['2026-04-22'], blocked: false, noCheckin: true },

    // Allow booking over, but no check-out
    { dates: ['2026-04-23'], blocked: false, noCheckout: true },

    // Block a holiday period
    { from: '2026-05-25', to: '2026-05-31', blocked: true },

    // Block lunch time slots every day
    {
      weekdays: ['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun'],
      blocked: false,
      blockedTimes: ['12:00-13:30'],
    },

    // Block morning slots on weekends
    { weekdays: ['sat', 'sun'], blocked: false, blockedTimes: ['08:00-10:00'] },

    // Block ALL time slots on specific dates
    {
      from: '2026-07-04',
      to: '2026-07-07',
      blockAllTimes: true,
      blocked: false,
    },
  ],
});

Rule selectors

Property	Type	Description
dates	(string | Date)[]	Match specific dates (YYYY-MM-DD)
from	string | Date	Range start (inclusive)
to	string | Date	Range end (inclusive)
weekdays	Weekday[]	Recurring weekdays ('mon'–'sun'). Combined with from/to to match weekdays within a range

Rule effects

Property	Type	Default	Description
blocked	boolean	true*	Fully block the day (unclickable, hatched)
noCheckin	boolean	false	Prevent starting a range on this day
noCheckout	boolean	false	Prevent ending a range on this day
blockedTimes	string[]	[]	Block time slots ('HH:MM-HH:MM' ranges or 'HH:MM' exact)
blockAllTimes	boolean	false	Block all time slots on matching days

* If no effect is specified, blocked: true is implied.

Runtime API

const cal = new ModoCalendar({ ... });

// Replace all rules
cal.setLockRules(newRules);

// Legacy API (still supported)
cal.setBlockedDates(['2026-06-20']);
cal.setNoRangeStartDates(['2026-06-22']);
cal.setNoRangeEndDates(['2026-06-23']);

presetsPlugin

Sidebar with quick-select preset date ranges.

import { presetsPlugin, presetRanges } from 'modo-calendar';

presetsPlugin({
  presets: [
    presetRanges.today(),
    presetRanges.next7Days(),
    presetRanges.thisWeekend(),
    presetRanges.nextWeekend(),
    presetRanges.nextWeek(),
    presetRanges.nextMonth(),
  ],
});

All preset labels are localized. Pass a language code to get translated labels:

presetsPlugin({
  presets: [
    presetRanges.today('en'), // "Today"
    presetRanges.next7Days('en'), // "Next 7 days"
    presetRanges.thisWeekend('es'), // "Este fin de semana"
    presetRanges.nextMonth('de'), // "Nächster Monat"
  ],
});

Built-in languages: fr (default), en, es, de, pt. Without a language argument, labels default to French.

### `dropdownPlugin`

Month and year dropdown selectors in the calendar header.

```ts
import { dropdownPlugin } from 'modo-calendar';

dropdownPlugin({ yearRange: [2024, 2027] });

i18nPlugin

Runtime locale switching with custom formatting.

import { i18nPlugin } from 'modo-calendar';

const i18n = i18nPlugin({
  locales: {
    fr: {
      locale: 'fr-FR',
      weekStartsOn: 1,
      placeholder: 'Choisir une date...',
    },
    en: { locale: 'en-US', weekStartsOn: 0, placeholder: 'Pick a date...' },
  },
  initialLocale: 'fr',
});

// Switch at runtime
i18n.setLocale('en');

Options

Option	Type	Default	Description
trigger	string | HTMLElement	—	CSS selector or element to attach to
mode	'single' | 'range' | 'multiple'	'range'	Selection mode
inline	string | boolean	false	Inline mode (CSS selector or true)
locale	string	'fr-FR'	Locale for formatting
plugins	CalendarPlugin[]	[]	Array of plugins
minDate	string | Date	—	Earliest selectable date
maxDate	string | Date	—	Latest selectable date
minRangeNights	number	—	Minimum nights for range mode
maxRangeNights	number	—	Maximum nights for range mode
maxMultipleDates	number	—	Max selections in multiple mode
classNames	CalendarClassNames	{}	BEM class overrides per slot
showStatusMessages	boolean	true	Show validation feedback messages
hiddenInput	HTMLInputElement	—	Custom hidden input for form data

Instance API

const cal = new ModoCalendar({ ... });

// Get current selection (works for all modes)
const sel = cal.getSelection();
// => { mode: 'range', dates: [Date, ...], start: Date, end: Date }
// => { mode: 'multiple', dates: [Date, Date, ...], start: null, end: null }
// => { mode: 'single', dates: [Date], start: Date, end: null }

// Clear all selected dates/times
cal.clearSelection();

// Programmatically set a range
cal.setRange('2026-04-10', '2026-04-15');

// Status messages
cal.setStatusMessage({ type: 'warning', text: 'Pick a weekday', autoHideDelay: 3000 });
cal.clearStatusMessage();

// Locale
cal.setLocale('en-US');
cal.setWeekStartsOn(0); // 0=Sun, 1=Mon
cal.getResolvedLocale(); // => 'en-US'

// Destroy
cal.destroy();

Events

const cal = new ModoCalendar({ ... });

cal.on('dateSelected', ({ date, mode }) => { ... });
cal.on('dateDeselected', ({ date, mode }) => { ... });
cal.on('rangeSelected', ({ start, end }) => { ... });
cal.on('rangeCleared', () => { ... });
cal.on('timeSelected', ({ date, time }) => { ... });
cal.on('monthChanged', ({ date, direction }) => { ... });
cal.on('calendarOpen', () => { ... });
cal.on('calendarClose', () => { ... });
cal.on('statusMessage', (state) => { ... });
cal.on('localeChanged', ({ locale }) => { ... });

Theming

All styles use CSS custom properties with --mc- prefix:

:root {
  --mc-accent: #2563eb;
  --mc-accent-fg: #fff;
  --mc-bg: #fff;
  --mc-fg: #0f172a;
  --mc-muted: #f1f5f9;
  --mc-border: #e2e8f0;
  --mc-danger: #ef4444;
  --mc-cell-radius: 0.5rem;
  --mc-font: 'Inter', system-ui, sans-serif;
  --mc-transition: 150ms ease;
}

Development

npm run dev       # Vite dev server
npm run build     # Production build (ESM + UMD)
npm run preview   # Preview production build

• Source: src/
• Plugins: src/plugins/
• Core styles: src/core/styles.css
• Demo: demo/index.html

Accessibility

ModoCalendar follows WCAG 2.1 guidelines:

• Focus trap inside the calendar popup (Tab / Shift+Tab cycle)
• aria-modal="true" on the calendar container
• aria-disabled="true" on blocked days (lock plugin)
• tabindex="0" on spinner buttons for keyboard access
• Preset groups use role="group" with aria-selected states
• Focus returns to the trigger on Escape
• Full keyboard navigation (arrow keys, Enter, Escape)

Plugin Hook Chain

Plugins can override core methods cleanly using the hook chain system instead of monkey-patching:

// Inside a plugin's onInit:
calendar._addHook('updateHiddenInput', (original) => {
  return function () {
    // Custom logic before/after/instead of original
    original();
  };
});
// Returns an unhook function to remove the override

Multiple plugins can hook the same method — hooks are chained in registration order.

License

MIT

---

2026 ModoCalendar