magic-datetime

Natural language datetime picker — type "next Friday at 3pm" and get a real date.

Framework-agnostic · Built with Lit · Powered by chrono-node · Styled via CSS variables

What it does

magic-datetime is a web component datetime picker with a twist: users can type plain English and get a real parsed date back. It works in any framework — or no framework at all.

"tomorrow at 9am"          → 2025-06-15T09:00:00
"next Friday at 3pm"       → 2025-06-20T15:00:00
"Jan 10 to Jan 20"         → { start: …, end: … }   (range mode)

On top of natural language, users can also navigate a calendar, select date ranges, and you can theme every pixel via --magic-* CSS tokens.

Documentation

Live demo: mubin-khalid.github.io/magic-datetime/demo/

Run the interactive docs locally:

pnpm install
pnpm dev        # → http://localhost:5173/demo/
pnpm build:demo # static site → dist-docs/ (same as GitHub Pages deploy)

| Page | What's covered | |---|---| | Overview | Purpose, quick try-it | | Getting started | Install, usage in HTML · React · Vue · Svelte · Angular | | Natural language | Supported phrases, hint pills, applyNaturalLanguage() | | Modes & ranges | mode="date", datetime, selection="range" | | Theming | Every --magic-* token, defaults, preset CSS, live preview | | API reference | All attributes, events, and methods | | Constraints | min / max / disabled |

Clone the repo and run pnpm dev for the interactive docs at http://localhost:5173/demo/.

Note: min / max are bounds on what can be selected, not a date range. For start–end values use selection="range".

Install

pnpm add magic-datetime lit
pnpm add open-props   # optional — for design tokens

lit is a peer dependency — install it alongside this package so your app does not bundle two copies of Lit.

Or use a CDN (ESM; also load Lit from a CDN):

<link rel="stylesheet" href="https://unpkg.com/open-props/open-props.min.css" />
<script type="importmap">
  {
    "imports": {
      "lit": "https://cdn.jsdelivr.net/npm/lit@3/+esm",
      "lit/": "https://cdn.jsdelivr.net/npm/lit@3/",
      "magic-datetime": "https://cdn.jsdelivr.net/npm/magic-datetime/dist/magic-datetime.js"
    }
  }
</script>
<script type="module">
  import 'magic-datetime';
</script>

<magic-datetime
  label="When?"
  placeholder='Try "tomorrow at 9am"'
></magic-datetime>

Quick API

Listening for changes

picker.addEventListener('magic-change', (e) => {
  e.detail.value; // string value (or { start, end } in range mode)
  e.detail.date;  // Date object (or { start, end })
});

Programmatic control

// Parse and apply a natural-language string
picker.applyNaturalLanguage('next Friday at 3pm', { confirm: true });

// Open the picker
picker.open();

Range mode

<magic-datetime
  selection="range"
  mode="date"
  placeholder='e.g. "Jan 10 to Jan 20"'
></magic-datetime>

Theming

Every visual surface is controlled by --magic-* CSS custom properties. Override them on the element or any ancestor:

magic-datetime {
  --magic-accent:       var(--teal-6);
  --magic-accent-light: var(--teal-1);
}

See the theming docs for the full token reference — every property, its default value, what it affects, and a live CSS preview.

Development

pnpm dev        # documentation site at /demo/
pnpm build      # compile library → dist/
pnpm typecheck  # TypeScript check

Contributing

Contributions are very welcome! Here's how to get started:

1. Fork the repo and clone it locally
2. Install dependencies: pnpm install
3. Start the dev server: pnpm dev
4. Create a branch: git checkout -b feat/your-feature
5. Make your changes, add tests if relevant
6. Open a Pull Request — describe what you changed and why

Please follow the existing code style. For larger changes, open an issue first to discuss the direction.

Bug reports: Use the GitHub Issues tab. Include a minimal reproduction if possible.

License

MIT © Mubin Khalid