# Calendar

A calendar component that allows users to select a date or a range of dates.

Source: https://webjs.dev/ui/docs/components/calendar

```ts
import { html } from '@webjsdev/core';

/** Today as the calendar's value string, "YYYY-MM-DD". */
function today(): string {
  const d = new Date();
  const pad = (n: number) => String(n).padStart(2, '0');
  return d.getFullYear() + '-' + pad(d.getMonth() + 1) + '-' + pad(d.getDate());
}

export default function CalendarDemo() {
  return html`
    <ui-calendar
      mode="single"
      value=${today()}
      class="rounded-lg border"
      caption-layout="dropdown"
    ></ui-calendar>
  `;
}
```

## Installation

```bash
npx @webjsdev/ui add calendar
```

### Copy and paste the following code into your project.

````ts title="components/ui/calendar.ts"
/**
 * Calendar: a month grid for picking a date, several dates, or a range.
 * Tier-2. shadcn's is react-day-picker; this is the same grid hand-rolled on
 * `Intl.DateTimeFormat`, with no dependency. The server renders the month, so
 * the grid is in the first paint; picking needs JavaScript.
 *
 * shadcn parity:
 *   Calendar mode="single" | "multiple" | "range"
 *                            → <ui-calendar mode value>
 *   selected                 → `value`: "2025-06-12"; for multiple a comma list;
 *                              for range "2025-06-12/2025-06-20"
 *   month / defaultMonth     → `month`: "2025-06" (the first month shown)
 *   numberOfMonths           → `number-of-months`
 *   showOutsideDays          → `show-outside-days="false"` hides them (shown by default)
 *   weekStartsOn             → `week-starts-on` (0 is Sunday, the default)
 *   showWeekNumber           → `show-week-number` (a leading column of week numbers)
 *   ISOWeek                  → `iso-week` (ISO 8601 weeks: Monday first, ISO numbers)
 *   captionLayout="dropdown" → `caption-layout="dropdown"` (month and year selects)
 *   disabled / startMonth / endMonth
 *                            → `min` / `max` ("2025-01-01"), and `disabled` for the whole grid
 *   locale                   → `locale` (a BCP 47 tag), else the page's `lang`
 *   onSelect                 → `ui-value-change` ({ detail: { value } }): a date string, a
 *                              string array, or { from, to } for a range
 *   onMonthChange            → `ui-month-change` ({ detail: { month } })
 *
 * With `name`, the value also rides hidden inputs, so a form submits it: one
 * input for a single date, one per date for multiple, and `name[from]` /
 * `name[to]` for a range.
 *
 * Keyboard (the WAI-ARIA date grid): one day is in the tab order. The arrows
 * move a day or a week (left and right swap under `dir="rtl"`), Home / End go
 * to the week's ends, PageUp / PageDown change the month and with Shift the
 * year, and Enter or Space picks. Moving past the shown months turns the page.
 *
 * A11y (handled by the element): each month is a `role="grid"` labelled by its
 * caption, every day button is named by its full date (and says "Today" and
 * "selected"), days outside `min` / `max` are disabled, and the previous and
 * next buttons are named.
 *
 * @example
 * ```html
 * <ui-calendar mode="single" value="2025-06-12" class="rounded-lg border"></ui-calendar>
 *
 * <ui-calendar mode="range" value="2025-06-12/2025-06-20" number-of-months="2" name="stay"></ui-calendar>
 * ```
 */
import { WebComponent, html, prop, signal, nothing } from '@webjsdev/core';
import { cn } from '../lib/utils.ts';
import { buttonClass } from './button.ts';

// --------------------------------------------------------------------------
// Date maths, all on UTC calendar dates written as YYYY-MM-DD, so a timezone
// can never move a day.
// --------------------------------------------------------------------------

/** A date-only value: the calendar's unit. */
export type CalendarDate = { y: number; m: number; d: number };

/** Parse "YYYY-MM-DD" (or "YYYY-MM", day 1); null when it is not a date. */
export function parseDate(s: string | null | undefined): CalendarDate | null {
  const m = /^(\d{4})-(\d{2})(?:-(\d{2}))?$/.exec((s ?? '').trim());
  if (!m) return null;
  const y = Number(m[1]);
  const mo = Number(m[2]) - 1;
  const d = m[3] ? Number(m[3]) : 1;
  const t = new Date(Date.UTC(y, mo, d));
  if (t.getUTCFullYear() !== y || t.getUTCMonth() !== mo || t.getUTCDate() !== d) return null;
  return { y, m: mo, d };
}

/** Format as "YYYY-MM-DD". */
export function formatDate(c: CalendarDate): string {
  return `${String(c.y).padStart(4, '0')}-${String(c.m + 1).padStart(2, '0')}-${String(c.d).padStart(2, '0')}`;
}

function toUTC(c: CalendarDate): Date {
  return new Date(Date.UTC(c.y, c.m, c.d));
}

function fromUTC(t: Date): CalendarDate {
  return { y: t.getUTCFullYear(), m: t.getUTCMonth(), d: t.getUTCDate() };
}

/** `c` moved by `days`. */
export function addDays(c: CalendarDate, days: number): CalendarDate {
  const t = toUTC(c);
  t.setUTCDate(t.getUTCDate() + days);
  return fromUTC(t);
}

/** `c` moved by `months`, clamped to the last day of the target month. */
export function addMonths(c: CalendarDate, months: number): CalendarDate {
  const first = new Date(Date.UTC(c.y, c.m + months, 1));
  const last = new Date(Date.UTC(first.getUTCFullYear(), first.getUTCMonth() + 1, 0)).getUTCDate();
  return { y: first.getUTCFullYear(), m: first.getUTCMonth(), d: Math.min(c.d, last) };
}

/** -1, 0 or 1. */
export function compareDates(a: CalendarDate, b: CalendarDate): number {
  return a.y - b.y || a.m - b.m || a.d - b.d;
}

/** Whether `a` and `b` are the same day. */
export function sameDay(a: CalendarDate | null, b: CalendarDate | null): boolean {
  return !!a && !!b && compareDates(a, b) === 0;
}

/**
 * The weeks of a month as rows of seven days, starting on `weekStartsOn`
 * (0 Sunday). Days of the neighbouring months fill the first and last rows;
 * there are only as many rows as the month needs.
 */
export function monthWeeks(y: number, m: number, weekStartsOn = 0): CalendarDate[][] {
  const first = { y, m, d: 1 };
  const lead = (toUTC(first).getUTCDay() - weekStartsOn + 7) % 7;
  const daysIn = new Date(Date.UTC(y, m + 1, 0)).getUTCDate();
  const total = Math.ceil((lead + daysIn) / 7) * 7;
  const start = addDays(first, -lead);
  const weeks: CalendarDate[][] = [];
  for (let i = 0; i < total; i += 7) {
    weeks.push(Array.from({ length: 7 }, (_, j) => addDays(start, i + j)));
  }
  return weeks;
}

/**
 * The number of the week `date` falls in, as the calendar labels a row, the
 * way react-day-picker numbers it. By default week 1 is the week holding
 * January 1, with weeks counted from `weekStartsOn` (date-fns getWeek, with
 * the en-US first week). With `iso` the week is ISO 8601's: weeks start on
 * Monday and week 1 holds the year's first Thursday (date-fns getISOWeek),
 * whatever `weekStartsOn` says.
 */
export function weekNumber(date: CalendarDate, weekStartsOn = 0, iso = false): number {
  const DAY = 86400000;
  const start = iso ? 1 : weekStartsOn;
  // The day of January that week 1 must contain.
  const anchor = iso ? 4 : 1;
  const startOfWeek = (ms: number): number => ms - ((new Date(ms).getUTCDay() - start + 7) % 7) * DAY;
  const at = Date.UTC(date.y, date.m, date.d);
  const firstOf = (y: number): number => startOfWeek(Date.UTC(y, 0, anchor));
  const year = at >= firstOf(date.y + 1) ? date.y + 1 : at >= firstOf(date.y) ? date.y : date.y - 1;
  return Math.round((startOfWeek(at) - firstOf(year)) / (7 * DAY)) + 1;
}

/** A range in progress or complete. */
export type CalendarRange = { from: CalendarDate | null; to: CalendarDate | null };

/**
 * The range after picking `day`: the first pick starts it, the second ends
 * it (swapping if it lies before the start), and a pick on a complete range
 * starts a new one.
 */
export function addToRange(range: CalendarRange, day: CalendarDate): CalendarRange {
  const { from, to } = range;
  if (!from || (from && to)) return { from: day, to: null };
  if (compareDates(day, from) < 0) return { from: day, to: from };
  return { from, to: day };
}

// --------------------------------------------------------------------------
// Classes
// --------------------------------------------------------------------------

/** The root's classes (the element applies them). */
export function calendarClass(): string {
  return 'p-3 [--cell-radius:var(--radius-md)] [--cell-size:--spacing(8)] group/calendar bg-background in-data-[slot=card-content]:bg-transparent in-data-[slot=popover-content]:bg-transparent rtl:**:[.rdp-button-next>svg]:rotate-180 rtl:**:[.rdp-button-previous>svg]:rotate-180';
}
/** A month caption's label. */
export const calendarCaptionClass = (): string => 'text-sm';
// shadcn names the dropdown caption's box and label `cn-calendar-dropdown-root`
// and `cn-calendar-caption-label`, but its build bakes only the first name of
// each component file, so `shadcn add` leaves both unstyled in every style and
// ui.shadcn.com draws neither a border nor a padded label. The kit gives them
// names only new-york maps, which keeps new-york's bordered dropdowns and
// matches shadcn's output in the other styles.
/** A dropdown caption's visible label. */
export const calendarCaptionLabelClass = (): string =>
  'h-8 ps-2 pe-1 flex items-center gap-1 rounded-(--cell-radius) text-sm [&>svg]:size-3.5 [&>svg]:text-muted-foreground';
/** A caption dropdown's box. */
export const calendarDropdownRootClass = (): string => 'border border-input shadow-xs has-focus:border-ring has-focus:ring-[3px] has-focus:ring-ring/50 relative rounded-(--cell-radius)';
/** A day button's classes (the element applies them). */
export const calendarDayButtonClass = (): string =>
  'relative isolate z-10 flex aspect-square size-auto w-full min-w-(--cell-size) flex-col gap-1 border-0 leading-none font-normal group-data-[focused=true]/day:relative group-data-[focused=true]/day:z-10 group-data-[focused=true]/day:border-ring group-data-[focused=true]/day:ring-[3px] group-data-[focused=true]/day:ring-ring/50 data-[range-end=true]:rounded-(--cell-radius) data-[range-end=true]:rounded-e-(--cell-radius) data-[range-end=true]:bg-primary data-[range-end=true]:text-primary-foreground data-[range-middle=true]:rounded-none data-[range-middle=true]:bg-muted data-[range-middle=true]:text-foreground data-[range-start=true]:rounded-(--cell-radius) data-[range-start=true]:rounded-s-(--cell-radius) data-[range-start=true]:bg-primary data-[range-start=true]:text-primary-foreground data-[selected-single=true]:bg-primary data-[selected-single=true]:text-primary-foreground dark:hover:text-foreground [&>span]:text-xs [&>span]:opacity-70';

const NAV_BUTTON = 'size-(--cell-size) p-0 select-none aria-disabled:opacity-50';

// --------------------------------------------------------------------------
// <ui-calendar>
// --------------------------------------------------------------------------

let uid = 0;

export class UiCalendar extends WebComponent({
  mode: prop<'single' | 'multiple' | 'range'>(String),
  value: String,
  name: String,
  month: String,
  numberOfMonths: prop(Number, { attribute: 'number-of-months' }),
  showOutsideDays: prop(String, { attribute: 'show-outside-days' }),
  weekStartsOn: prop(Number, { attribute: 'week-starts-on' }),
  showWeekNumber: prop(Boolean, { attribute: 'show-week-number' }),
  isoWeek: prop(Boolean, { attribute: 'iso-week' }),
  captionLayout: prop<'label' | 'dropdown'>(String, { attribute: 'caption-layout' }),
  min: String,
  max: String,
  disabled: Boolean,
  locale: String,
}) {
  // The live state: what is chosen, which month is shown, which day has focus.
  readonly #selection = signal<{ days: string[]; from: string; to: string }>({ days: [], from: '', to: '' });
  readonly #shown = signal('');
  readonly #focused = signal('');
  _id = '';
  _parsed = false;

  constructor() {
    super();
    this.mode = 'single';
    this.value = '';
    this.name = '';
    this.month = '';
    this.numberOfMonths = 1;
    this.showOutsideDays = 'true';
    this.weekStartsOn = 0;
    this.showWeekNumber = false;
    this.isoWeek = false;
    this.captionLayout = 'label';
    this.min = '';
    this.max = '';
    this.disabled = false;
    this.locale = '';
  }

  connectedCallback(): void {
    super.connectedCallback?.();
    this._id ||= `ui-calendar-${++uid}`;
  }

  // Read the attributes into state once, on the first render (server or client).
  willUpdate(changedProperties: Map<string, unknown>): void {
    super.willUpdate?.(changedProperties);
    if (this._parsed) return;
    this._parsed = true;
    const v = this.value ?? '';
    if (this.mode === 'range') {
      const [a, b] = v.split('/');
      const from = parseDate(a);
      const to = parseDate(b);
      this.#selection.set({ days: [], from: from ? formatDate(from) : '', to: to ? formatDate(to) : '' });
    } else {
      const days = (this.mode === 'multiple' ? v.split(',') : [v]).map(parseDate).filter((d): d is CalendarDate => !!d).map(formatDate);
      this.#selection.set({ days, from: '', to: '' });
    }
    const picked = this.#selection.get();
    const anchor = parseDate(this.month) ?? parseDate(picked.from || picked.days[0]) ?? this._today();
    this.#shown.set(formatDate({ y: anchor.y, m: anchor.m, d: 1 }));
  }

  _today(): CalendarDate {
    const n = new Date();
    return { y: n.getFullYear(), m: n.getMonth(), d: n.getDate() };
  }

  _locale(): string {
    if (this.locale) return this.locale;
    const lang = typeof document !== 'undefined' ? document.documentElement?.lang : '';
    return lang || 'en-US';
  }

  _fmt(opts: Intl.DateTimeFormatOptions): Intl.DateTimeFormat {
    return new Intl.DateTimeFormat(this._locale(), { ...opts, timeZone: 'UTC' });
  }

  _min(): CalendarDate | null {
    return parseDate(this.min);
  }

  _max(): CalendarDate | null {
    return parseDate(this.max);
  }

  _isDisabled(day: CalendarDate): boolean {
    if (this.disabled) return true;
    const lo = this._min();
    const hi = this._max();
    return (!!lo && compareDates(day, lo) < 0) || (!!hi && compareDates(day, hi) > 0);
  }

  _first(): CalendarDate {
    return parseDate(this.#shown.get()) ?? this._today();
  }

  /** The value in the shape `ui-value-change` reports. */
  get selected(): string | string[] | { from: string; to: string } {
    const s = this.#selection.get();
    if (this.mode === 'range') return { from: s.from, to: s.to };
    if (this.mode === 'multiple') return [...s.days];
    return s.days[0] ?? '';
  }

  /** Pick `iso`, as a click or Enter does. */
  pick(iso: string): void {
    const day = parseDate(iso);
    if (!day || this._isDisabled(day)) return;
    const s = this.#selection.get();
    if (this.mode === 'range') {
      const next = addToRange({ from: parseDate(s.from), to: parseDate(s.to) }, day);
      this.#selection.set({ days: [], from: next.from ? formatDate(next.from) : '', to: next.to ? formatDate(next.to) : '' });
    } else if (this.mode === 'multiple') {
      const days = s.days.includes(iso) ? s.days.filter((d) => d !== iso) : [...s.days, iso].sort();
      this.#selection.set({ days, from: '', to: '' });
    } else {
      this.#selection.set({ days: s.days[0] === iso ? [] : [iso], from: '', to: '' });
    }
    this.#focused.set(iso);
    this.dispatchEvent(new CustomEvent('ui-value-change', { bubbles: true, detail: { value: this.selected } }));
  }

  /** Show the month containing `iso` first. */
  goToMonth(iso: string): void {
    const day = parseDate(iso);
    if (!day) return;
    const next = formatDate({ y: day.y, m: day.m, d: 1 });
    if (next === this.#shown.get()) return;
    this.#shown.set(next);
    this.dispatchEvent(new CustomEvent('ui-month-change', { bubbles: true, detail: { month: next.slice(0, 7) } }));
  }

  _canGo(by: number): boolean {
    const first = this._first();
    const lo = this._min();
    const hi = this._max();
    if (by < 0 && lo) return compareDates(addMonths(first, -1), { y: lo.y, m: lo.m, d: 1 }) >= 0;
    if (by > 0 && hi) {
      const lastShown = addMonths(first, (this.numberOfMonths || 1) - 1);
      return compareDates(addMonths(lastShown, 1), { y: hi.y, m: hi.m, d: 1 }) <= 0;
    }
    return true;
  }

  _turn(by: number): void {
    if (!this._canGo(by)) return;
    this.goToMonth(formatDate(addMonths(this._first(), by)));
  }

  // The state a day is drawn in.
  _dayState(day: CalendarDate): { selected: boolean; single: boolean; start: boolean; end: boolean; middle: boolean } {
    const s = this.#selection.get();
    const iso = formatDate(day);
    if (this.mode === 'range') {
      const from = parseDate(s.from);
      const to = parseDate(s.to);
      const start = sameDay(day, from);
      const end = sameDay(day, to);
      const middle = !!from && !!to && compareDates(day, from) > 0 && compareDates(day, to) < 0;
      // A range of one day (or one not yet ended) draws its start as a single pick.
      const lone = start && (!to || sameDay(from, to));
      return { selected: start || end || middle, single: lone, start: start && !lone, end: end && !lone, middle };
    }
    const on = s.days.includes(iso);
    return { selected: on, single: on, start: false, end: false, middle: false };
  }

  // The day that owns the tab stop: the focused one, else the first chosen
  // day shown, else today if shown, else the first day of the first month.
  _tabDay(months: CalendarDate[]): string {
    const inShown = (iso: string) => {
      const d = parseDate(iso);
      return !!d && months.some((m) => m.y === d.y && m.m === d.m);
    };
    const focused = this.#focused.get();
    if (focused && inShown(focused)) return focused;
    const s = this.#selection.get();
    const chosen = [s.from, ...s.days].find((d) => d && inShown(d));
    if (chosen) return chosen;
    const today = formatDate(this._today());
    if (inShown(today)) return today;
    return formatDate(months[0]);
  }

  render() {
    const months = Array.from({ length: Math.max(1, this.numberOfMonths || 1) }, (_, i) => addMonths(this._first(), i));
    const tab = this._tabDay(months);
    const today = formatDate(this._today());
    const outside = this.showOutsideDays !== 'false';
    const weekday = this._fmt({ weekday: 'short' });
    const weekdayLong = this._fmt({ weekday: 'long' });
    const caption = this._fmt({ month: 'long', year: 'numeric' });
    const full = this._fmt({ weekday: 'long', year: 'numeric', month: 'long', day: 'numeric' });
    const en = this._locale().toLowerCase().startsWith('en');
    const headerDays = monthWeeks(2024, 0, this._weekStart())[1];
    const dropdown = this.captionLayout === 'dropdown';
    const weeks = !!this.showWeekNumber;
    const hidden = this.name ? this._hiddenInputs() : '';
    return html`<div
      data-slot="calendar"
      class=${cn('w-fit', calendarClass())}
      @keydown=${this._onKeyDown}
    ><div class="relative flex flex-col gap-4 md:flex-row"><nav aria-label="Navigation" class="absolute inset-x-0 top-0 flex w-full items-center justify-between gap-1"><button
      type="button"
      aria-label="Go to the Previous Month"
      aria-disabled=${this._canGo(-1) ? nothing : 'true'}
      class=${cn(buttonClass({ variant: 'ghost' }), NAV_BUTTON, 'rdp-button-previous')}
      @click=${() => this._turn(-1)}
    ><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" class="cn-rtl-flip size-4 rtl:rotate-180"><path d="m15 18-6-6 6-6"></path></svg></button><button
      type="button"
      aria-label="Go to the Next Month"
      aria-disabled=${this._canGo(1) ? nothing : 'true'}
      class=${cn(buttonClass({ variant: 'ghost' }), NAV_BUTTON, 'rdp-button-next')}
      @click=${() => this._turn(1)}
    ><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" class="cn-rtl-flip size-4 rtl:rotate-180"><path d="m9 18 6-6-6-6"></path></svg></button></nav>${months.map((mo, mi) => {
      // No id before connect (the server never connects an element): a served
      // `-caption-0` would be shared by every calendar on the page.
      const captionId = this._id ? `${this._id}-caption-${mi}` : nothing;
      return html`<div class="flex w-full flex-col gap-4"><div class="flex h-(--cell-size) w-full items-center justify-center px-(--cell-size)">${dropdown && mi === 0
        ? this._dropdowns(mo, captionId)
        : html`<span id=${captionId} role="status" aria-live="polite" class=${cn('font-medium select-none', calendarCaptionClass())}>${caption.format(toUTC(mo))}</span>`}</div><table
        role="grid"
        aria-labelledby=${captionId}
        aria-multiselectable=${this.mode === 'single' ? nothing : 'true'}
        class="w-full border-collapse"
      ><thead aria-hidden="true"><tr class="flex">${weeks
        ? html`<th scope="col" aria-label="Week Number" class="w-(--cell-size) select-none"></th>`
        : ''}${headerDays.map((d) => {
        const short = weekday.format(toUTC(d));
        return html`<th scope="col" aria-label=${weekdayLong.format(toUTC(d))} class="flex-1 rounded-(--cell-radius) text-[0.8rem] font-normal text-muted-foreground select-none">${en ? short.slice(0, 2) : short}</th>`;
      })}</tr></thead><tbody>${monthWeeks(mo.y, mo.m, this._weekStart()).map((week) => html`<tr class="mt-2 flex w-full">${weeks
        ? this._weekNumberCell(week)
        : ''}${week.map((day) => {
        const iso = formatDate(day);
        const isOutside = day.m !== mo.m;
        if (isOutside && !outside) {
          return html`<td role="gridcell" class="group/day relative aspect-square h-full w-full p-0 invisible"></td>`;
        }
        const st = this._dayState(day);
        const off = this._isDisabled(day);
        const isToday = iso === today;
        const label = `${isToday ? 'Today, ' : ''}${full.format(toUTC(day))}${st.selected ? ', selected' : ''}`;
        return html`<td
          role="gridcell"
          data-day=${iso}
          aria-selected=${st.selected ? 'true' : nothing}
          data-selected=${st.selected ? 'true' : nothing}
          data-today=${isToday ? 'true' : nothing}
          data-outside=${isOutside ? 'true' : nothing}
          data-disabled=${off ? 'true' : nothing}
          data-focused=${this.#focused.get() === iso ? 'true' : nothing}
          class=${cn(
            'group/day relative aspect-square h-full w-full rounded-(--cell-radius) p-0 text-center select-none [&:last-child[data-selected=true]_button]:rounded-e-(--cell-radius) [&:first-child[data-selected=true]_button]:rounded-s-(--cell-radius)',
            // A week-number column makes the row's first day its second cell,
            // which takes the first day's corner instead.
            weeks ? '[&:nth-child(2)[data-selected=true]_button]:rounded-s-(--cell-radius)' : '',
            st.start ? 'relative isolate z-0 rounded-s-(--cell-radius) bg-muted after:absolute after:inset-y-0 after:end-0 after:w-4 after:bg-muted' : '',
            st.middle ? 'rounded-none' : '',
            st.end ? 'relative isolate z-0 rounded-e-(--cell-radius) bg-muted after:absolute after:inset-y-0 after:start-0 after:w-4 after:bg-muted' : '',
            isToday ? 'rounded-(--cell-radius) bg-muted text-foreground data-[selected=true]:rounded-none' : '',
            isOutside ? 'text-muted-foreground aria-selected:text-muted-foreground' : '',
            off ? 'text-muted-foreground opacity-50' : '',
          )}
        ><button
          type="button"
          tabindex=${iso === tab ? '0' : '-1'}
          aria-label=${label}
          ?disabled=${off}
          data-day=${iso}
          data-selected-single=${st.single ? 'true' : 'false'}
          data-range-start=${st.start ? 'true' : 'false'}
          data-range-end=${st.end ? 'true' : 'false'}
          data-range-middle=${st.middle ? 'true' : 'false'}
          class=${cn(buttonClass({ variant: 'ghost', size: 'icon' }), calendarDayButtonClass())}
          @click=${() => this.pick(iso)}
          @focus=${() => { this.#focused.set(iso); }}
        >${day.d}</button></td>`;
      })}</tr>`)}</tbody></table></div>`;
    })}</div>${hidden}</div>`;
  }

  // The first day of a week: Monday for ISO weeks, as react-day-picker's
  // ISOWeek lays them out, else `week-starts-on`.
  _weekStart(): number {
    return this.isoWeek ? 1 : this.weekStartsOn || 0;
  }

  // A row's week number, a header cell for the row as react-day-picker draws
  // it: named "Week N" and shown two digits wide.
  _weekNumberCell(week: CalendarDate[]): unknown {
    const n = weekNumber(week[0], this._weekStart(), !!this.isoWeek);
    return html`<td role="rowheader" scope="row" aria-label=${`Week ${n}`} class="text-[0.8rem] text-muted-foreground select-none"><div class="flex size-(--cell-size) items-center justify-center text-center">${String(n).padStart(2, '0')}</div></td>`;
  }

  _hiddenInputs(): unknown {
    const s = this.#selection.get();
    if (this.mode === 'range') {
      return html`<input type="hidden" name=${`${this.name}[from]`} value=${s.from}><input type="hidden" name=${`${this.name}[to]`} value=${s.to}>`;
    }
    return s.days.map((d) => html`<input type="hidden" name=${this.name} value=${d}>`);
  }

  // Month and year selects over the caption, as react-day-picker draws them.
  _dropdowns(mo: CalendarDate, captionId: string | typeof nothing): unknown {
    const monthName = this._fmt({ month: 'short' });
    const lo = this._min() ?? { y: mo.y - 100, m: 0, d: 1 };
    const hi = this._max() ?? { y: mo.y + 10, m: 11, d: 31 };
    const years: number[] = [];
    for (let y = lo.y; y <= hi.y; y++) years.push(y);
    const months = Array.from({ length: 12 }, (_, i) => i);
    const chevron = html`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m6 9 6 6 6-6"></path></svg>`;
    return html`<div id=${captionId} class="flex h-(--cell-size) w-full items-center justify-center gap-1.5 text-sm font-medium"><span class=${calendarDropdownRootClass()}><select
      aria-label="Choose the Month"
      class="absolute inset-0 bg-popover opacity-0"
      @change=${(e: Event) => this.goToMonth(formatDate({ y: mo.y, m: Number((e.target as HTMLSelectElement).value), d: 1 }))}
    >${months.map((m) => html`<option value=${String(m)} ?selected=${m === mo.m}>${monthName.format(toUTC({ y: mo.y, m, d: 1 }))}</option>`)}</select><span
      aria-hidden="true" class=${cn('font-medium select-none', calendarCaptionLabelClass())}>${monthName.format(toUTC(mo))}${chevron}</span></span><span class=${calendarDropdownRootClass()}><select
      aria-label="Choose the Year"
      class="absolute inset-0 bg-popover opacity-0"
      @change=${(e: Event) => this.goToMonth(formatDate({ y: Number((e.target as HTMLSelectElement).value), m: mo.m, d: 1 }))}
    >${years.map((y) => html`<option value=${String(y)} ?selected=${y === mo.y}>${y}</option>`)}</select><span
      aria-hidden="true" class=${cn('font-medium select-none', calendarCaptionLabelClass())}>${mo.y}${chevron}</span></span></div>`;
  }

  _onKeyDown = (e: KeyboardEvent): void => {
    const target = e.target as HTMLElement;
    const iso = target.getAttribute?.('data-day');
    if (!iso || target.tagName !== 'BUTTON') return;
    const day = parseDate(iso);
    if (!day) return;
    const rtl = typeof getComputedStyle === 'function' && getComputedStyle(this).direction === 'rtl';
    const w = this._weekStart();
    let next: CalendarDate | null = null;
    switch (e.key) {
      case 'ArrowLeft': next = addDays(day, rtl ? 1 : -1); break;
      case 'ArrowRight': next = addDays(day, rtl ? -1 : 1); break;
      case 'ArrowUp': next = addDays(day, -7); break;
      case 'ArrowDown': next = addDays(day, 7); break;
      case 'Home': next = addDays(day, -((toUTC(day).getUTCDay() - w + 7) % 7)); break;
      case 'End': next = addDays(day, 6 - ((toUTC(day).getUTCDay() - w + 7) % 7)); break;
      case 'PageUp': next = e.shiftKey ? addMonths(day, -12) : addMonths(day, -1); break;
      case 'PageDown': next = e.shiftKey ? addMonths(day, 12) : addMonths(day, 1); break;
      case 'Enter':
      case ' ':
        e.preventDefault();
        this.pick(iso);
        return;
      default:
        return;
    }
    e.preventDefault();
    this.focusDay(formatDate(next));
  };

  /** Move focus to `iso`, turning the page when it is not shown. */
  focusDay(iso: string): void {
    const day = parseDate(iso);
    if (!day) return;
    const first = this._first();
    const last = addMonths(first, (this.numberOfMonths || 1) - 1);
    if (compareDates({ ...day, d: 1 }, { ...first, d: 1 }) < 0) this.goToMonth(iso);
    else if (compareDates({ ...day, d: 1 }, { ...last, d: 1 }) > 0) this.goToMonth(formatDate(addMonths(day, -((this.numberOfMonths || 1) - 1))));
    this.#focused.set(iso);
    this.updateComplete.then(() => {
      this.querySelector<HTMLButtonElement>(`button[data-day="${iso}"]`)?.focus();
    });
  }
}
UiCalendar.register('ui-calendar');
````

### Update the import paths to match your project setup.

## Usage

```ts
import '#components/ui/calendar.ts';
```

```ts
<ui-calendar
  mode="single"
  value="2025-06-12"
  class="rounded-lg border"
  @ui-value-change=${(e) => console.log(e.detail.value)}
></ui-calendar>
```

The selection is the `value` attribute, a `"YYYY-MM-DD"` string, and every pick dispatches `ui-value-change`. See the API Reference for the rest of its attributes.

## About

`<ui-calendar>` is a month grid built on `Intl.DateTimeFormat`, with no dependency. The server renders the month, so the grid is in the first paint, and picking a day needs JavaScript.

## Date Picker

You can use `<ui-calendar>` to build a date picker. See the [Date Picker](https://webjs.dev/ui/docs/components/date-picker) page for more information.

## Persian / Hijri / Jalali Calendar

`<ui-calendar>` lays out Gregorian months. What a `locale` changes is the language its months and weekdays are named in, so a Persian locale gives Persian names over Gregorian dates, as below. Add `-u-ca-gregory` to the locale so the caption names the same month the grid shows.

```ts
<ui-calendar mode="single" locale="fa-IR-u-ca-gregory" dir="rtl"></ui-calendar>
```

```ts
import { html } from '@webjsdev/core';

// <ui-calendar> lays its grid out in the Gregorian calendar and names it
// through Intl.DateTimeFormat, so a Persian locale gives Persian month and
// weekday names over Gregorian dates. The -u-ca-gregory extension keeps the
// caption on the same calendar as the grid.
export default function CalendarHijri() {
  return html`
    <div dir="rtl" lang="fa">
      <ui-calendar
        mode="single"
        value="2025-06-12"
        month="2025-06"
        locale="fa-IR-u-ca-gregory"
        class="rounded-lg border"
      ></ui-calendar>
    </div>
  `;
}
```

## Selected Date (With TimeZone)

A selected day never drifts by one between time zones: `<ui-calendar>` values are date-only strings, `"YYYY-MM-DD"`, and its arithmetic runs on UTC calendar dates, so a time zone can never move a day.

```ts
<ui-calendar
  mode="single"
  @ui-value-change=${(e) => {
    // "2025-06-20", whatever time zone the browser is in
    const day = e.detail.value;
  }}
></ui-calendar>
```

**Note:** the one value that does depend on where the reader is, the day marked as today, is read from the clock of whatever renders the calendar, the server's on the first paint and the browser's once the element renders again.

## Basic

A basic calendar. We used `class="rounded-lg border"` to style the calendar.

```ts
import { html } from '@webjsdev/core';

export default function CalendarBasic() {
  return html`<ui-calendar mode="single" class="rounded-lg border"></ui-calendar>`;
}
```

## Range Calendar

Use `mode="range"` to enable range selection. The value is `"from/to"`, and `number-of-months` shows more than one month.

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { cardClass, cardContentClass } from '#components/ui/card.ts';

const pad = (n: number) => String(n).padStart(2, '0');

export default function CalendarRange() {
  const now = new Date();
  const year = now.getFullYear();
  const today = year + '-' + pad(now.getMonth() + 1) + '-' + pad(now.getDate());

  return html`
    <div data-slot="card" data-size="default" class=${cn(cardClass(), 'mx-auto w-fit p-0')}>
      <div data-slot="card-content" class=${cn(cardContentClass(), 'p-0')}>
        <ui-calendar
          mode="range"
          value=${year + '-01-12/' + year + '-02-11'}
          month=${year + '-01'}
          number-of-months="2"
          min="1900-01-01"
          max=${today}
        ></ui-calendar>
      </div>
    </div>
  `;
}
```

## Month and Year Selector

Use `caption-layout="dropdown"` to show month and year dropdowns.

```ts
import { html } from '@webjsdev/core';

export default function CalendarCaption() {
  return html`
    <ui-calendar
      mode="single"
      caption-layout="dropdown"
      class="rounded-lg border"
    ></ui-calendar>
  `;
}
```

## Presets

Presets are buttons beside the calendar that set its `value` and `month`. The component that owns the card wires each button's click.

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { buttonClass } from '#components/ui/button.ts';
import { cardClass, cardContentClass, cardFooterClass } from '#components/ui/card.ts';

const pad = (n: number) => String(n).padStart(2, '0');

const PRESETS = [
  { label: 'Today', value: 0 },
  { label: 'Tomorrow', value: 1 },
  { label: 'In 3 days', value: 3 },
  { label: 'In a week', value: 7 },
  { label: 'In 2 weeks', value: 14 },
];

// Each preset button carries its offset in days. Wiring the click (set the
// calendar's value and month to today plus the offset) is a few lines in the
// component that owns this card.
export default function CalendarWithPresets() {
  const now = new Date();
  const year = now.getFullYear();

  return html`
    <div data-slot="card" data-size="sm" class=${cn(cardClass({ size: 'sm' }), 'mx-auto w-fit max-w-[300px]')}>
      <div data-slot="card-content" class=${cardContentClass()}>
        <ui-calendar
          mode="single"
          value=${year + '-02-12'}
          month=${year + '-' + pad(now.getMonth() + 1)}
          class="*:data-[slot=calendar]:p-0 *:data-[slot=calendar]:[--cell-size:--spacing(9.5)]"
        ></ui-calendar>
      </div>
      <div data-slot="card-footer" class=${cn(cardFooterClass(), 'flex flex-wrap gap-2 border-t')}>
        ${PRESETS.map((preset) => html`
          <button type="button" data-slot="button" data-variant="outline" data-size="sm" data-days=${preset.value} class=${cn(buttonClass({ variant: 'outline', size: 'sm' }), 'flex-1')}>
            ${preset.label}
          </button>
        `)}
      </div>
    </div>
  `;
}
```

## Date and Time Picker

The calendar picks a day only. Pair it with native `<input type="time">` fields for the time, as below.

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { cardClass, cardContentClass, cardFooterClass } from '#components/ui/card.ts';
import { fieldClass, fieldGroupClass, fieldLabelClass } from '#components/ui/field.ts';
import {
  inputGroupClass, inputGroupAddonClass, inputGroupInputClass,
} from '#components/ui/input-group.ts';
import { Clock2Icon } from '#lib/ui/lucide.ts';

const pad = (n: number) => String(n).padStart(2, '0');

const TIME_INPUT = 'appearance-none [&::-webkit-calendar-picker-indicator]:hidden [&::-webkit-calendar-picker-indicator]:appearance-none';

export default function CalendarWithTime() {
  const now = new Date();

  return html`
    <div data-slot="card" data-size="sm" class=${cn(cardClass({ size: 'sm' }), 'mx-auto w-fit')}>
      <div data-slot="card-content" class=${cardContentClass()}>
        <ui-calendar
          mode="single"
          value=${now.getFullYear() + '-' + pad(now.getMonth() + 1) + '-12'}
          class="*:data-[slot=calendar]:p-0"
        ></ui-calendar>
      </div>
      <div data-slot="card-footer" class=${cn(cardFooterClass(), 'border-t bg-card')}>
        <div data-slot="field-group" class=${fieldGroupClass()}>
          <div role="group" data-slot="field" data-orientation="vertical" class=${fieldClass()}>
            <label data-slot="field-label" for="time-from" class=${fieldLabelClass()}>Start Time</label>
            <div data-slot="input-group" role="group" class=${inputGroupClass()}>
              <input data-slot="input-group-control" id="time-from" type="time" step="1" value="10:30:00" class=${cn(inputGroupInputClass(), TIME_INPUT)}>
              <label data-slot="input-group-addon" data-align="inline-start" for="time-from" class=${inputGroupAddonClass()}>
                ${Clock2Icon('text-muted-foreground')}
              </label>
            </div>
          </div>
          <div role="group" data-slot="field" data-orientation="vertical" class=${fieldClass()}>
            <label data-slot="field-label" for="time-to" class=${fieldLabelClass()}>End Time</label>
            <div data-slot="input-group" role="group" class=${inputGroupClass()}>
              <input data-slot="input-group-control" id="time-to" type="time" step="1" value="12:30:00" class=${cn(inputGroupInputClass(), TIME_INPUT)}>
              <label data-slot="input-group-addon" data-align="inline-start" for="time-to" class=${inputGroupAddonClass()}>
                ${Clock2Icon('text-muted-foreground')}
              </label>
            </div>
          </div>
        </div>
      </div>
    </div>
  `;
}
```

## Booked dates

`<ui-calendar>` disables the days outside a `min` / `max` window, or the whole grid with `disabled`. This demo closes the booked end of February with `max`.

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { cardClass, cardContentClass } from '#components/ui/card.ts';

// <ui-calendar> disables the days outside its min / max window. It takes no
// list of single days, so here the bookings from the 12th onwards close the
// rest of February through `max`.
export default function CalendarBookedDates() {
  const year = new Date().getFullYear();

  return html`
    <div data-slot="card" data-size="default" class=${cn(cardClass(), 'mx-auto w-fit p-0')}>
      <div data-slot="card-content" class=${cn(cardContentClass(), 'p-0')}>
        <ui-calendar
          mode="single"
          value=${year + '-02-03'}
          month=${year + '-02'}
          max=${year + '-02-11'}
        ></ui-calendar>
      </div>
    </div>
  `;
}
```

## Custom Cell Size

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { cardClass, cardContentClass } from '#components/ui/card.ts';

export default function CalendarCustomDays() {
  const year = new Date().getFullYear();

  return html`
    <div data-slot="card" data-size="default" class=${cn(cardClass(), 'mx-auto w-fit p-0')}>
      <div data-slot="card-content" class=${cn(cardContentClass(), 'p-0')}>
        <ui-calendar
          mode="range"
          value=${year + '-12-08/' + year + '-12-18'}
          month=${year + '-12'}
          caption-layout="dropdown"
          class="*:data-[slot=calendar]:[--cell-size:--spacing(10)] md:*:data-[slot=calendar]:[--cell-size:--spacing(12)]"
        ></ui-calendar>
      </div>
    </div>
  `;
}
```

You can customize the size of calendar cells using the `--cell-size` CSS variable. The element's root sets its own default, so set the variable on that root, the element's `data-slot="calendar"` child. You can also make it responsive by using breakpoint-specific values:

```ts
<ui-calendar
  mode="single"
  class="rounded-lg border *:data-[slot=calendar]:[--cell-size:--spacing(11)] md:*:data-[slot=calendar]:[--cell-size:--spacing(12)]"
></ui-calendar>
```

Or use fixed values:

```ts
<ui-calendar
  mode="single"
  class="rounded-lg border *:data-[slot=calendar]:[--cell-size:2.75rem] md:*:data-[slot=calendar]:[--cell-size:3rem]"
></ui-calendar>
```

`<ui-calendar>` renders its own day buttons and offers no slot for extra content in them, such as a price under each day.

## Week Numbers

Use `show-week-number` to show week numbers. Week 1 is the week that holds January 1. Add `iso-week` for ISO 8601 weeks, which start on Monday and number from the week that holds the year's first Thursday.

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { cardClass, cardContentClass } from '#components/ui/card.ts';

// February with the 3rd selected, each row led by its week number.
export default function CalendarWeekNumbers() {
  const year = new Date().getFullYear();

  return html`
    <div data-slot="card" data-size="default" class=${cn(cardClass(), 'mx-auto w-fit p-0')}>
      <div data-slot="card-content" class=${cn(cardContentClass(), 'p-0')}>
        <ui-calendar
          mode="single"
          value=${year + '-02-03'}
          month=${year + '-02'}
          show-week-number
        ></ui-calendar>
      </div>
    </div>
  `;
}
```

## RTL

To enable RTL support, see the [RTL configuration guide](https://webjs.dev/ui/docs/rtl).

See also the Hijri Guide for what the calendar offers for Persian / Hijri / Jalali calendars.

```ts
import { html } from '@webjsdev/core';

const locales = {
  ar: 'ar',
  he: 'he',
} as const;

const pad = (n: number) => String(n).padStart(2, '0');

// The provider is the dir attribute plus the locale: the calendar flips its
// arrows and range ends by logical side, and names its months and weekdays
// through Intl.DateTimeFormat in the language you pass.
export default function CalendarRtl() {
  const lang = 'ar';
  const now = new Date();
  const today = now.getFullYear() + '-' + pad(now.getMonth() + 1) + '-' + pad(now.getDate());

  return html`
    <ui-calendar
      mode="single"
      value=${today}
      caption-layout="dropdown"
      dir="rtl"
      lang=${lang}
      locale=${locales[lang]}
      class="rounded-lg border *:data-[slot=calendar]:[--cell-size:--spacing(9)]"
    ></ui-calendar>
  `;
}
```

When using RTL, set `dir="rtl"` on the calendar or an ancestor, and pass the language as `locale`, a BCP 47 tag. Without one the calendar reads the page's `lang`.

```ts
<ui-calendar
  mode="single"
  locale="ar"
  dir="rtl"
></ui-calendar>
```

## API Reference

`<ui-calendar>` takes the following attributes.

| Attribute | Type | Default |
| --- | --- | --- |
| `mode` | `"single" \| "multiple" \| "range"` | `"single"` |
| `value` | `string`: `"2025-06-12"`, a comma list for multiple, `"2025-06-12/2025-06-20"` for a range | - |
| `month` | `string`: `"2025-06"`, the first month shown | the value's month, else today's |
| `number-of-months` | `number` | `1` |
| `caption-layout` | `"label" \| "dropdown"` | `"label"` |
| `show-outside-days` | `"true" \| "false"` | `"true"` |
| `week-starts-on` | `number` (0 is Sunday) | `0` |
| `show-week-number` | `boolean` | `false` |
| `iso-week` | `boolean`: ISO 8601 weeks, starting on Monday | `false` |
| `min` / `max` | `string`: `"2025-01-01"` | - |
| `disabled` | `boolean` | `false` |
| `locale` | `string`, a BCP 47 tag | the page's `lang` |
| `name` | `string`: submits the value in hidden inputs | - |

With `name`, the value rides hidden inputs, so a form submits it: one input for a single date, one per date for multiple, and `name[from]` / `name[to]` for a range.

| Event | Detail |
| --- | --- |
| `ui-value-change` | `{ value }`: a date string, a string array, or `{ from, to }` for a range |
| `ui-month-change` | `{ month }`: `"2025-06"` |

One day is in the tab order. The arrow keys move a day or a week, Home and End go to the week's ends, PageUp and PageDown change the month (with Shift, the year), and Enter or Space picks.

## Changelog

### RTL Support

`<ui-calendar>` supports right-to-left layouts and localized labels out of the box: it takes `locale`, formats every label with it, and rounds range ends with logical properties (`rounded-s` / `rounded-e`, `start` / `end`), so `dir="rtl"` flips the grid with no other change.

If you copied `components/ui/calendar.ts` before it took `locale`, run `webjs ui diff calendar` to see what changed and `webjs ui add calendar --overwrite` to take the current version.

```ts
<ui-calendar mode="single" locale="en-US"></ui-calendar>
```
