Skip to content
WebJs
Menu

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

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>
  `;
}
View Code

Installation

pnpm dlx @webjsdev/ui add calendar

Usage

import '#components/ui/calendar.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 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.

<ui-calendar mode="single" locale="fa-IR-u-ca-gregory" dir="rtl"></ui-calendar>
ژوئن ۲۰۲۵
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>
  `;
}
View Code

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.

<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.

November 2026
import { html } from '@webjsdev/core';

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

Range Calendar

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

January 2026
February 2026
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>
  `;
}
View Code

Month and Year Selector

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

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

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

Presets

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

November 2026
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>
  `;
}
View Code

Date and Time Picker

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

November 2026
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>
  `;
}
View Code

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.

February 2026
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>
  `;
}
View Code

Custom Cell Size

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>
  `;
}
View Code

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:

<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:

<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.

February 2026
06
07
08
09
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>
  `;
}
View Code

RTL

To enable RTL support, see the RTL configuration guide.

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

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>
  `;
}
View Code

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.

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

API Reference

<ui-calendar> takes the following attributes.

AttributeTypeDefault
mode"single" | "multiple" | "range""single"
valuestring: "2025-06-12", a comma list for multiple, "2025-06-12/2025-06-20" for a range-
monthstring: "2025-06", the first month shownthe value's month, else today's
number-of-monthsnumber1
caption-layout"label" | "dropdown""label"
show-outside-days"true" | "false""true"
week-starts-onnumber (0 is Sunday)0
show-week-numberbooleanfalse
iso-weekboolean: ISO 8601 weeks, starting on Mondayfalse
min / maxstring: "2025-01-01"-
disabledbooleanfalse
localestring, a BCP 47 tagthe page's lang
namestring: 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.

EventDetail
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.

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