Calendar

A month-grid date picker with optional month-picking mode and Temporal.PlainDate binding.

Usage

Use standalone.

Svelte

<Calendar {...props} />

Anatomy

The class attribute values represent part names, and conditional indicates elements that are rendered conditionally. Other attributes represent their corresponding props. While picking, children renders inside middle and wins over the embedded MonthPicker.

Svelte

<div class="whole" role="group">
  <div class="top">
    <button class="left" type="button">{left}</button>
    <button class="label" type="button">{label}</button>
    <button class="right" type="button">{right}</button>
  </div>
  <div class="middle">
    <div class="main" role="grid">
      <div class="aux" role="row" data-header>
        <span class="extra" role="columnheader" data-header>{weekday}</span>
      </div>
      <div class="aux" role="row">
        <button class="extra" role="gridcell">{day}</button>
      </div>
    </div>
    {#if children}{children}{:else}<MonthPicker />{/if} while picking
  </div>
  <div class="bottom" conditional>{bottom}</div>
</div>

Left and right buttons page display; the label button toggles picking.
While picking, children renders in the middle slot and wins over the embedded MonthPicker.
The bottom snippet receives a control object (setToday, clear), the picking state, and the variant.
Enabled day clicks and Enter or Space select one Temporal.PlainDate.
Day cells expose data-today, data-selected, data-outside, data-disabled, and data-weekday.
The weekday header row and each week row both use the aux part; only the header row and its column headers carry data-header, which separates header-only from day-only styling.
Arrow keys, Home, End, PageUp, PageDown, and Shift+PageUp/PageDown update roving focus.

Props

Name	Type	Default	Description
`value`	`Temporal.PlainDate`	-	Bindable selected date
`display`	`Temporal.PlainYearMonth`	-	Bindable shown year-month for calendar paging
`picking`	`boolean`	`false`	Bindable state that shows the embedded `MonthPicker` instead of the day grid
`min`	`Temporal.PlainDate`	-	Lower date bound; dates before it are disabled
`max`	`Temporal.PlainDate`	-	Upper date bound; dates after it are disabled
`isDisabled`	`(d: Temporal.PlainDate) => boolean`	-	Custom predicate that disables matching dates
`outsideDays`	`boolean`	`false`	Show outside-month days in the grid
`fixedWeeks`	`boolean`	`false`	Render a fixed six-week grid
`firstDayOfWeek`	`number`	`0`	First weekday, where `0` = Sunday
`locale`	`string`	-	Locale for weekday and heading labels
`label`	`Snippet`	-	Heading snippet
`left`	`Snippet`	-	Previous-button snippet
`right`	`Snippet`	-	Next-button snippet
`weekday`	`Snippet`	-	Weekday label snippet
`day`	`Snippet`	-	Day cell snippet
`bottom`	`Snippet`	-	Bottom-area snippet; receives a control object (`setToday`, `clear`), the `picking` state, and the variant
`children`	`Snippet`	-	Overrides the middle slot while picking; wins over `monthPicker`
`monthPicker`	`MonthPickerProps`	-	Nested config bag spread into the embedded `MonthPicker`; `Calendar` owns the displayed month, bounds, and variant
`transition`	`TransitionProp`	-	Optional transition function and params for switching between the day grid and month picker
`pageTransition`	`TransitionProp`	-	Optional transition that slides the day grid when `display` pages
`styling`	`SVSClass`	-	Styling override
`variant`	`SVSVariant`	`NEUTRAL`	Variant passed to navigation and container parts

Styling

To learn more, see Styling.

Variant Management

Selected days render with active, disabled days render with inactive, and other day cells use neutral. Navigation and container parts receive the supplied variant.

Default Class Name

svs-calendar

Behavior

Left/right buttons page display; the label toggles the picking slot.
While picking, children renders in the middle slot and wins over the embedded MonthPicker.
The bottom snippet receives a control object (setToday, clear), the picking state, and the variant.
Enabled day clicks and Enter/Space select a single Temporal.PlainDate.
Day cells expose data-today, data-selected, data-outside, data-disabled, and data-weekday.
Arrow, Home/End, PageUp/PageDown, and Shift+PageUp/PageDown update roving focus.
The grid re-keys when display changes; optional pageTransition applies to the day-grid page change.

Accessibility

Keyboard Interactions

Key	Description
`ArrowLeft` / `ArrowRight`	Moves focus one day backward or forward
`ArrowUp` / `ArrowDown`	Moves focus one week backward or forward
`Home` / `End`	Moves focus to the start or end of the focused week
`PageUp` / `PageDown`	Moves focus one month backward or forward
`Shift` + `PageUp` / `Shift` + `PageDown`	Moves focus one year backward or forward
`Enter` / `Space`	Selects the focused day

Clicking an enabled day also selects it.

ARIA Roles and Attributes

The component applies these automatically:

Root (whole): role="group" and aria-label generated from the current displayed month.
Caption button (label): aria-expanded for the month/year picker state.
Grid (main): role="grid" and aria-labelledby pointing to the caption button; it contains weekday and week rows.
Weekday row (aux): role="row" containing column headers.
Weekday header: role="columnheader" with an aria-label for the full weekday name.
Day cell: role="gridcell", roving tabindex, aria-selected, aria-disabled, aria-current="date" on today, and a per-date aria-label.

The root already has a built-in accessible name such as the current month. Provide clear custom label, left, right, and day snippets if you replace the default visible text.

Exports

Types

TypeScript

interface CalendarProps {
  value?: Temporal.PlainDate; // bindable; selected date
  display?: Temporal.PlainYearMonth; // bindable; shown month
  picking?: boolean; // bindable (false)
  min?: Temporal.PlainDate;
  max?: Temporal.PlainDate;
  isDisabled?: (d: Temporal.PlainDate) => boolean;
  outsideDays?: boolean; // (false)
  fixedWeeks?: boolean; // (false)
  firstDayOfWeek?: number; // (0=Sun)
  locale?: string;
  label?: Snippet<[Temporal.PlainYearMonth, string, boolean]>;
  left?: Snippet<[string]>;
  right?: Snippet<[string]>;
  weekday?: Snippet<[number, string]>;
  day?: Snippet<[DayCtx]>;
  bottom?: Snippet<[CalendarCtl, boolean, string]>;
  children?: Snippet;
  monthPicker?: Omit<MonthPickerProps, "value" | "min" | "max" | "variant">;
  transition?: TransitionProp;
  pageTransition?: TransitionProp;
  styling?: SVSClass;
  variant?: SVSVariant; // (VARIANT.NEUTRAL)
}
type CalendarReqdProps = never;
type CalendarBindProps = "value" | "display" | "picking";
type DayCtx = {
  date: Temporal.PlainDate;
  variant: string;
  weekday: number;
  today: boolean;
  selected: boolean;
  outside: boolean;
  disabled: boolean;
};
type CalendarCtl = {
  setToday: () => void;
  clear: () => void;
};
type TransitionProp = {
  fn?: (node: HTMLElement, params: any, options: { direction: "in" | "out" | "both" }) => import("svelte/transition").TransitionConfig;
  params?: unknown;
};

Others

No additional exports are available.

Examples

The example code uses Tailwind CSS along with SVSClass.

Basic

Svelte

<script lang="ts">
  import { Calendar } from "svseeds";

  let value = $state<Temporal.PlainDate>();
  const childStyle1 = {
    whole: "relative flex items-center rounded-md bg-white dark:bg-black",
    left: "absolute inset-y-0 inset-x-1 my-auto h-7 rounded-md opacity-30 bg-black dark:bg-white pointer-events-none",
  };
  const childStyle2 = {
    whole: "w-35 h-30 overflow-hidden rounded-md",
    middle: "h-full",
    label: {
      base: "flex h-8 items-center justify-end",
      active: "font-bold",
    },
    aux: "hidden",
    extra: "inset-0 bg-linear-to-b from-white via-transparent to-white dark:from-black dark:to-black",
  };
  const childStyle3 = {
    ...childStyle2,
    whole: "w-35 h-30 overflow-hidden rounded-md",
    label: {
      base: "flex ps-4 h-8 items-center justify-start",
      active: "font-bold",
    },
  };
  const childProps = {
    styling: childStyle1,
    left,
    yearLabel: (y: number) => String(y),
    monthLabel: (m: number) => String(m).padStart(2, "0"),
    year: { styling: childStyle2 },
    month: { styling: childStyle3 },
  };
  const styling = {
    whole: "w-72 rounded-md border bg-white p-3 dark:bg-black",
    top: "mb-3 flex items-center gap-2",
    left: "px-2 py-1 rounded-md border text-sm cursor-pointer",
    label: "min-w-0 flex-1 cursor-pointer rounded-md border px-2 py-1 text-sm font-bold",
    right: "px-2 py-1 rounded-md border text-sm cursor-pointer",
    middle: "overflow-hidden",
    aux: "grid grid-cols-7 gap-1 pb-1 font-bold",
    main: "grid gap-1 outline-hidden",
    extra: {
      base: "flex size-8 items-center justify-center rounded-md text-sm data-header:data-[weekday=0]:text-red-500 data-outside:text-gray-400 data-today:font-bold data-today:not-data-selected:bg-gray-400",
      active: "bg-teal-500 font-bold",
      inactive: "text-gray-400",
    },
  };
  const myProps = {
    styling,
    monthPicker: childProps,
    outsideDays: true,
  };
</script>

<div class="flex flex-col items-center gap-3">
  <Calendar bind:value {...myProps}>
    {#snippet left()}{"<"}{/snippet}
    {#snippet right()}{">"}{/snippet}
  </Calendar>
  <div class="text-sm">Selected: {value?.toString() ?? "Pick a day"}</div>
</div>
{#snippet left()}{/snippet}

With Interactive Variant

Preset for Demo

Free Input

Enter variant as you like

Svelte

<script lang="ts">
  import { cubicInOut } from "svelte/easing";
  import { Calendar } from "svseeds";

  let { variant = $bindable() } = $props();
  let value = $state<Temporal.PlainDate>();
  function slide(_node: HTMLElement, params: { dir?: number; duration?: number }, { direction }: { direction: "in" | "out" | "both" }) {
    const dir = params.dir ?? 0;
    const entering = direction === "in";
    return {
      duration: params.duration ?? 250,
      easing: cubicInOut,
      css: (t: number) => {
        const offset = (1 - t) * (entering ? dir : -dir) * 100;
        const overlay = entering ? "" : "position:absolute;inset:0;";
        return `${overlay}transform:translateX(${offset}%);`;
      },
    };
  }

  const variantStyle = {
    neutral: "border-gray-400",
    active: "border-teal-500",
    inactive: "border-red-500",
    blue: "border-blue-500",
    yellow: "border-yellow-500",
    sky: "border-sky-500",
  };
  const childStyle1 = {
    whole: "relative flex items-center rounded-md bg-white dark:bg-black",
    left: "absolute inset-y-0 inset-x-1 my-auto h-7 rounded-md opacity-30 bg-black dark:bg-white pointer-events-none",
  };
  const childStyle2 = {
    whole: "w-35 h-30 overflow-hidden rounded-md",
    middle: "h-full",
    label: {
      base: "flex h-8 items-center justify-end",
      active: "font-bold",
    },
    aux: "hidden",
    extra: "inset-0 bg-linear-to-b from-white via-transparent to-white dark:from-black dark:to-black",
  };
  const childStyle3 = {
    ...childStyle2,
    whole: "w-35 h-30 overflow-hidden rounded-md",
    label: {
      base: "flex ps-4 h-8 items-center justify-start",
      active: "font-bold",
    },
  };
  const childProps = {
    styling: childStyle1,
    left,
    yearLabel: (y: number) => String(y),
    monthLabel: (m: number) => String(m).padStart(2, "0"),
    year: { styling: childStyle2 },
    month: { styling: childStyle3 },
  };
  const styling = {
    whole: {
      base: "w-72 rounded-md border bg-white p-3 dark:bg-black",
      ...variantStyle,
    },
    top: "mb-3 flex items-center gap-2",
    left: "px-2 py-1 rounded-md border text-sm cursor-pointer order-2",
    label: "min-w-0 flex-1 cursor-pointer px-2 font-bold underline order-1",
    right: "px-2 py-1 rounded-md border text-sm cursor-pointer order-3",
    middle: "relative overflow-hidden",
    aux: "grid grid-cols-7 gap-1 not-data-header:pb-1 data-header:font-bold data-header:border-b border-gray-400",
    main: "grid gap-1 outline-hidden",
    extra: {
      base: "flex size-8 items-center justify-center rounded-md text-sm data-header:data-[weekday=0]:text-red-500 data-outside:text-gray-400 data-today:not-data-selected:bg-gray-400",
      active: "bg-teal-500 font-bold",
      inactive: "text-gray-400",
    },
    bottom: "pt-3 text-center",
  };
  const myProps = {
    styling,
    monthPicker: childProps,
    outsideDays: true,
    fixedWeeks: true,
    pageTransition: { fn: slide },
  };
</script>

<div class="flex flex-col items-center gap-3">
  <Calendar bind:value {variant} {...myProps}>
    {#snippet label(ym)}
      {ym.toString()}
    {/snippet}
    {#snippet left()}{"<"}{/snippet}
    {#snippet right()}{">"}{/snippet}
    {#snippet bottom(ctl)}
      <button class="rounded-md border px-3 py-1 text-sm cursor-pointer" type="button" onclick={ctl.setToday}>Today</button>
    {/snippet}
  </Calendar>
  <div class="text-sm">Selected: {value?.toString() ?? "Pick a day"}</div>
</div>
{#snippet left()}{/snippet}