@w3cj/magic-date-picker

A magical date picker web component with natural language date input.

Installation

# npm
npm install @w3cj/magic-date-picker

# pnpm
pnpm add @w3cj/magic-date-picker

# yarn
yarn add @w3cj/magic-date-picker

CDN

<script src="https://unpkg.com/@w3cj/magic-date-picker/dist/magic-date-picker.cdn.js"></script>

The CDN bundle is an IIFE with all dependencies bundled. It self-registers the <magic-date-picker> element — no additional setup needed.

Bundled Build

A pre-bundled ESM build with all dependencies included is available at @w3cj/magic-date-picker/bundled:

import "@w3cj/magic-date-picker/bundled";

This is useful when you don't want to install or manage the peer dependencies yourself (e.g. in environments without a bundler, or when you want a single-file ESM import).

Peer Dependencies

The default export (@w3cj/magic-date-picker) externalizes the following dependencies. They are listed in dependencies and will be installed automatically, but if your setup requires manual installation:

• lit ^3.3.2
• chrono-node ^2.9.0
• date-fns ^4.1.0

If you use the @w3cj/magic-date-picker/bundled or CDN builds, these are already included and no additional packages are needed.

Quick Start

<script type="module">
  import "@w3cj/magic-date-picker";
</script>

<magic-date-picker></magic-date-picker>

Attributes

| Attribute | Type | Default | Description | | ------------- | ------- | ------- | -------------------------------------------- | | placeholder | string | — | Custom placeholder text | | enable-time | boolean | false | Show the time picker | | locale | string | — | Locale string for date formatting | | disabled | boolean | false | Disable all interaction | | readonly | boolean | false | Allow viewing but not editing | | theme | string | auto | "light" | "dark" | "auto" | | value | string | "" | ISO 8601 date string (reflected, read/write) |

Properties

| Property | Type | Description | | -------- | ------------------------------------- | --------------------------------------- | | value | string | ISO 8601 string of the resolved date(s) | | output | DatePickerOutput \| null | Full structured output (getter) | | output | { start: Date, end?: Date } \| null | Programmatic date setter |

value

A reflected HTML attribute containing the ISO 8601 representation of the current selection. Updated automatically on every date-change and date-clear event. Can also be set to programmatically select a date — the ISO string is parsed and resolved internally.

Date-only (no enable-time):

• Single date: "2026-04-20"
• Range: "2026-04-20/2026-04-25" (ISO 8601 interval)
• Empty: "" (clears selection)

With enable-time:

• Single date: "2026-04-20T15:30:00.000Z"
• Range: "2026-04-20T15:30:00.000Z/2026-04-25T09:00:00.000Z"

const picker = document.querySelector("magic-date-picker");

// Read
console.log(picker.value); // "2026-04-20"
console.log(picker.getAttribute("value")); // same — it's reflected

// Write
picker.value = "2026-04-20"; // single date
picker.value = "2026-04-20/2026-04-25"; // range
picker.value = ""; // clear

output

The rich object form of the resolved date. Use the getter to read, the setter to programmatically set dates.

// Read
const out = picker.output; // DatePickerOutput | null
console.log(out?.start.iso, out?.isRange);

// Write
picker.output = { start: new Date("2026-04-20") };
picker.output = { start: new Date("2026-04-20"), end: new Date("2026-04-25") };
picker.output = null; // clear

Events

| Event | Detail Type | Description | | ------------- | ------------------ | ------------------------------------------------------------------------------- | | date-change | DatePickerOutput | Fires when a date is selected | | date-clear | — | Fires when the selection is cleared | | date-parse | DateParseDetail | Fires on every successful parse, BEFORE resolve — includes ambiguous alternates |

DatePickerOutput

type DatePickerOutput = {
  start: { iso: string; unix: number };
  end: { iso: string; unix: number };
  isRange: boolean;
  includesTime: boolean;
  text: string;
};

end is always present. For single-date outputs, end === start. Use isRange to distinguish single vs range semantics.

text is the canonical, locale-formatted rendering of the selected date or range (e.g. "Mon, Apr 20, 2026", "Mon, Apr 20, 2026 at 3:00 PM", or "Mon, Apr 20, 2026 to Sun, Apr 26, 2026"), not the original text the user typed. On every date resolution — Enter, suggestion click, calendar click, or time-picker change — the input field itself is also rewritten to this canonical form so the user sees exactly what was parsed. Round-tripping text back through the parser is guaranteed to yield the same span.

DateParseDetail

type DateParseDetail = {
  text: string; // original input at the moment of parse
  results: ParsedDateSpan[]; // all parsed interpretations (primary first)
  alternativesDescription?: string; // human-readable summary when results.length > 1
};

date-parse fires every time the parser successfully interprets the input, before the auto-resolve step. This gives consumers a live feed of parse state — including ambiguous interpretations (e.g. "3/4" can be March 4 or April 3) — which is useful for external previews, analytics, or debugging. When more than one interpretation exists, alternativesDescription mirrors the screen-reader announcement (e.g. "2 possible interpretations: Fri, Mar 4, 2026, or Sun, Apr 3, 2026. Use arrow keys to select.").

API Reference

Component

import { MagicDatePicker } from "@w3cj/magic-date-picker";

Types

import type {
  DatePickerOutput,
  DateSpan,
  HolidayEntry,
  ParsedDateSpan,
  ParseResult,
  RangeBuildingResult,
} from "@w3cj/magic-date-picker";

Utilities

import {
  buildOutput, // Build a DatePickerOutput from dates
  findHoliday, // Look up a holiday by name
  formatCanonical, // Canonical, round-trip-safe display form
  formatForAccessibility, // Screen-reader friendly form
  formatForPreview, // Canonical + duration suffix for ranges
  HOLIDAYS, // Built-in holiday list
  parse, // Parse a natural language date string
  VERSION, // Current version string
} from "@w3cj/magic-date-picker";

Development

pnpm install        # Install dependencies
pnpm dev            # Start Vite dev server
pnpm build          # Library build (ESM + CJS + bundled ESM + types)
pnpm build:cdn      # CDN IIFE bundle
pnpm test           # Vitest + Playwright tests
pnpm lint           # Lint
pnpm lint:fix       # Lint with auto-fix
pnpm typecheck      # TypeScript type checking

License

MIT