@19h47/calendar

@19h47/calendar

Lightweight date / range picker. Markup and CSS are yours — the package fills the grid and handles selection.

Installation

pnpm add @19h47/calendar

Markup

Required hooks:

Selector	Role
Root element	Passed to new Calendar(el, options)
.js-previous / .js-next	Month navigation (optional)
.js-title	Month / year label; click advances to the next month (same as .js-next)
.js-days	Weekday headers row
.js-body	Day cells
.js-day	Day button (generated)

<div class="Calendar js-calendar">
	<header>
		<button type="button" class="js-previous">Previous</button>
		<button type="button" class="js-title" id="calendar-label" aria-live="polite"></button>
		<button type="button" class="js-next">Next</button>
	</header>
	<table role="grid" aria-labelledby="calendar-label">
		<thead>
			<tr class="js-days"></tr>
		</thead>
		<tbody class="js-body"></tbody>
	</table>
</div>

Usage

import Calendar, { type Options } from "@19h47/calendar";

const el = document.querySelector(".js-calendar") as HTMLElement;
const options: Partial<Options> = {
	locale: "fr",
	deselect: true,
	buttonClass: "btn btn-outline-primary", // optional — lib ships unstyled buttons
};

const calendar = new Calendar(el, options);
calendar.init();

el.addEventListener("Calendar.change", ({ detail }) => {
	// detail.values → string[] (`YYYY-MM-DD`)
	console.log(detail.values);
});

destroy() detaches listeners and clears the grid.

Single date

new Calendar(el, { single: true, deselect: true }).init();

Date range

new Calendar(el, { single: false }).init();

Locale & week start

locale drives labels via Intl. Week start defaults from the locale (weekInfo); pass firstDay to override.

new Calendar(el, { locale: "fr" }).init();
// fr → week starts Monday

new Calendar(el, { locale: "en", firstDay: 1 }).init();
// force Monday despite en

Update at runtime:

import Calendar, { getWeekStart } from "@19h47/calendar";

calendar.options.locale = "ja";
calendar.options.firstDay = getWeekStart("ja");
calendar.render();

Custom labels

new Calendar(el, {
	locale: "fr",
	days: ["Dim", "Lun", "Mar", "Mer", "Jeu", "Ven", "Sam"],
	months: [
		"Janvier", "Février", "Mars", "Avril", "Mai", "Juin",
		"Juillet", "Août", "Septembre", "Octobre", "Novembre", "Décembre",
	],
}).init();

Cell hook

Override renderInner to enrich or rebuild each day cell. Keep .js-day and data-day.

calendar.renderInner = (inner, date) => {
	const button = inner.querySelector(".js-day");
	if (!button) return;

	button.classList.add("MyDay");
	button.innerHTML = `<time datetime="${date.toISOString().slice(0, 10)}">${date.getDate()}</time>`;
};

Pair with custom stateClasses / header markup — see the Custom markup demo in index.html.

Options

Option	Type	Default	Description
locale	string	document.documentElement.lang or "en"	BCP 47 locale for title and weekday/month labels
buttonClass	string	""	Extra classes on day buttons (e.g. Bootstrap)
months	string[]	—	Month names override (Jan→Dec). Defaults to Intl
days	string[]	—	Weekday labels override (Sun→Sat). Defaults to Intl
single	boolean	true	Single date vs range
firstDay	number	from locale	Week start (0=Sun … 6=Sat)
deselect	boolean	false	Allow clearing the selection in single mode
allowPast	boolean	false	Allow selecting past dates
name	string	—	Forwarded in Calendar.change detail
stateClasses	object	see source	Selection classes (active, range, start, end)

Exported types: Options, StateClasses, Current. Also exported: getWeekStart, toDayString, fromDayString.

Attributes

Attribute	Description
data-month	Initial month (0–11)
data-year	Initial year
data-picked-dates	JSON array of YYYY-MM-DD days to preselect, e.g. ["2023-11-05","2023-11-07"]

Accessibility

The calendar grid follows the WAI-ARIA APG date grid practices.

In your markup (source of truth): role="grid", aria-labelledby, aria-live on the title, aria-label on nav buttons, etc.

Generated by the lib:

• Roving tabindex (one focusable day at a time)
• aria-selected on selected days
• aria-disabled on unavailable days (still in the keyboard grid)
• aria-current="date" on today
• Weekday headers with abbr (full day name)

Keyboard (focus in the grid)

Key	Action
Arrow keys	Move by day / week (crosses months)
Home / End	First / last day of the week
Page Up / Page Down	Previous / next month (same day number, or last day of month)
Shift + Page Up / Down	Previous / next year
Enter / Space	Select the focused day

Events

Calendar.change — fired on selection change.

detail: {
	values: string[]; // `YYYY-MM-DD`
	name?: string;
}

Live demos

• GitHub Pages (from docs/)
• Local: pnpm dev then open the app (see index.html)

Refresh the Pages demo after lib changes:

pnpm run docs

Acknowledgments

• Litepicker
• WAI-ARIA APG — Date Picker Dialog