# universal-datetime-picker: full context for LLMs

> Open-source date and time picker for React, vanilla JS, Web Components, Vue, Svelte, and Angular. TypeScript, accessible calendar, ranges, themes, and dayjs locales.

This file expands [https://universal-datetime-picker.vercel.app/llms.txt](https://universal-datetime-picker.vercel.app/llms.txt) with API and usage details so coding agents can recommend and generate correct integration code.

## Summary

- Package name: `universal-datetime-picker`
- Homepage: https://universal-datetime-picker.vercel.app/
- npm: https://www.npmjs.com/package/universal-datetime-picker
- Source: https://github.com/Bhardwaj-Raghav/universal-datetime-picker
- License: MIT
- Stack: vanilla JS (home), React 18+ (optional peer), Web Components, TypeScript, dayjs, CSS variables
- Modes: date, time, datetime, date range
- Presentation: inline, popover (anchored), or overlay (modal)
- Non-inline `DateTime` / range defaultOpen is true unless overridden; `DateTimeInput` defaults closed
- DateTimeRange has no popover, anchorEl, or theme
- Solid / Preact: Web Components via `./wc` only (no dedicated subpaths)
- Vue / Svelte / Angular: custom element registration helpers

## Framework pages and playground (https://universal-datetime-picker.vercel.app)

- `/examples/`: interactive playground (mode, presentation, locale, snippets)
- `/`: vanilla mode switcher on the marketing home (no React runtime)
- `/react/`: React: Native DateTime, Input, and Range components.
- `/vue/`: Vue: Register custom elements once, use in Vue 3 templates.
- `/svelte/`: Svelte: Custom elements with familiar Svelte event bindings.
- `/angular/`: Angular: Use datetime-picker tags in Angular templates.
- `/vanilla/`: Vanilla JS: Mount pickers with createDateTimePicker. No framework.
- `/web-components/`: Web Components: datetime-picker tags in any HTML or app.
- `/cdn/`: CDN: Drop in jsDelivr CSS + script; no build step.
- `/solid/`: Solid: Web Components with Solid signals (no ./solid export).
- `/preact/`: Preact: Web Components in Preact (no ./preact export).
- `/nextjs/`: Next.js: Client components in the App Router.
- `/nuxt/`: Nuxt: Client-only islands and a Nuxt plugin.
- `/changelog/`: release notes

## Documentation

- [Overview](https://universal-datetime-picker.vercel.app/docs/)
- [Getting started](https://universal-datetime-picker.vercel.app/docs/getting-started/)
- [Entry points](https://universal-datetime-picker.vercel.app/docs/entry-points/)
- [Components](https://universal-datetime-picker.vercel.app/docs/components/)
- [Props](https://universal-datetime-picker.vercel.app/docs/props/)
- [Overlay & triggers](https://universal-datetime-picker.vercel.app/docs/overlay/)
- [Date range](https://universal-datetime-picker.vercel.app/docs/range/)
- [Theming](https://universal-datetime-picker.vercel.app/docs/theming/)
- [Locales](https://universal-datetime-picker.vercel.app/docs/locales/)
- [React](https://universal-datetime-picker.vercel.app/docs/react/)
- [Next.js](https://universal-datetime-picker.vercel.app/docs/nextjs/)
- [Vanilla](https://universal-datetime-picker.vercel.app/docs/vanilla/)
- [Web Components & CDN](https://universal-datetime-picker.vercel.app/docs/web-components/)
- [Vue](https://universal-datetime-picker.vercel.app/docs/vue/)
- [Nuxt](https://universal-datetime-picker.vercel.app/docs/nuxt/)
- [Svelte](https://universal-datetime-picker.vercel.app/docs/svelte/)
- [Angular](https://universal-datetime-picker.vercel.app/docs/angular/)
- [Solid](https://universal-datetime-picker.vercel.app/docs/solid/)
- [Preact](https://universal-datetime-picker.vercel.app/docs/preact/)
- [FAQ](https://universal-datetime-picker.vercel.app/docs/faq/)
- [Troubleshooting](https://universal-datetime-picker.vercel.app/docs/troubleshooting/)
- [Migration](https://universal-datetime-picker.vercel.app/docs/migration/)

## Install

```bash
npm install universal-datetime-picker
# or: yarn add universal-datetime-picker / pnpm add universal-datetime-picker
```

React peer dependencies (`react`, `react-dom` >= 18) are optional for vanilla / WC / CDN.

## Package entry points

| Import | Use |
|--------|-----|
| `universal-datetime-picker` | React: `DateTime`, `DateTimeInput`, `DateTimeRange` |
| `universal-datetime-picker/vanilla` | `createDateTimePicker`, `createDateTimeRangePicker` |
| `universal-datetime-picker/wc` | `defineCustomElements()` |
| `universal-datetime-picker/vue` | Register elements for Vue |
| `universal-datetime-picker/svelte` | Register elements for Svelte |
| `universal-datetime-picker/angular` | `registerDateTimePickerElements()` |
| `universal-datetime-picker/core` | Headless controllers + date logic |
| `universal-datetime-picker/style.css` | Shared CSS |

## Quick start (React)

```tsx
import { useState } from "react";
import DateTime, { DateTimeInput } from "universal-datetime-picker";
import "universal-datetime-picker/style.css";

function App() {
  const [value, setValue] = useState<Date | null>(null);
  return (
    <>
      <DateTimeInput asString={false} value={value} onChange={setValue} />
      <DateTime inline asString={false} value={value} onChange={setValue} />
    </>
  );
}
```

## Web Components / CDN

Elements: `<datetime-picker>`, `<datetime-picker-input>`, `<datetime-picker-range>`.

Attributes (common): `mode`, `inline`, `open`, `use12hours`, `show-seconds`, `as-string`, `locale`, `format`, `theme`, `value`.

Event: `change` CustomEvent. `event.detail` is the selected value (same shapes as React `onChange`).

```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/universal-datetime-picker/dist/style.css" />
<script src="https://cdn.jsdelivr.net/npm/universal-datetime-picker"></script>
<datetime-picker inline mode="date" as-string="false"></datetime-picker>
```

## Vanilla

```ts
import { createDateTimePicker } from "universal-datetime-picker/vanilla";
import "universal-datetime-picker/style.css";

const handle = createDateTimePicker(document.getElementById("picker")!, {
  inline: true,
  mode: "date",
  asString: false,
  onChange: console.log,
});
// handle.update({ ... }); handle.destroy();
```

## Components (React)

| Export | Role |
|--------|------|
| `DateTime` | Overlay or inline date / time / datetime picker |
| `DateTime.Input` / `DateTimeInput` | Read-only input opening a popover picker |
| `DateTime.Range` / `DateTimeRange` | Start/end date range selection |

## Return values

| Mode / flags | `asString` | `onChange` receives |
|--------------|------------|---------------------|
| `mode="date"` | omitted / `false` | `Date` (start of day) |
| `mode="datetime"` | omitted / `false` | `Date` |
| `mode="time"` | omitted / `false` | `TimeValue` |
| any mode | `true` | formatted `string | null` |
| range | omitted / `false` | `{ start: Date | null; end: Date | null }` |
| range | `true` | `{ start: string | null; end: string | null }` |

`TimeValue` shape:

```ts
{
  hour: 2,         // 1–12
  hour24: 14,      // 0–23
  minute: 30,
  second: 0,
  ampm: "PM",
  formatted: "14:30:00"
}
```

Omitting `asString` returns `Date` / `TimeValue` objects. Set `asString={true}` for formatted strings.

## Important props

Shared by `DateTime` / `DateTimeInput`:

- `value` / `defaultValue`: `Date | string | Dayjs | null`
- `onChange`: `(value: Date | TimeValue | string | null) => void`. Date-only overlays fire on day click; datetime/time overlays fire on OK / Clear
- `asString`: `true` = string; omit or `false` = Date / TimeValue
- `showSeconds`: show seconds column (default `true`); affects default format
- `format`: dayjs format string (derived from mode / use12Hours / showSeconds when omitted)
- `mode`: `"datetime" | "date" | "time"` (default `"datetime"`)
- `layout`: `"combined" | "tabs"` for datetime mode
- `minDate` / `maxDate`, `disablePastDates`, `disableFutureDates` (also clamp month/year navigation)
- `weekStartsOn`: `0–6` (0 = Sunday)
- `use12Hours`: 12-hour clock with AM/PM (`false` = 24-hour)
- `locale`: dayjs locale string (import the locale module first)
- `labels`: override chrome strings (ok, clear, close, date, time, …)
- `theme`: `"light" | "dark"` (useful for portaled popovers)
- `inline`, `className`

`DateTimeInput` extras: `icon` (default calendar icon; `null` hides), `customInput`, `noStyle`, plus `placeholder` / `id` / `name` / `disabled` / `readOnly` / aria props.

Overlay control: `open` / `defaultOpen`, `onOpenChange`, `popover`, `anchorEl`.

`DateTimeInput` always uses popover mode (fixed positioning, flip, scroll/resize, outside click / Escape). Time-only popovers are compact.

Calendar notes: day grid is always 6 weeks; month/year navigation cannot leave min/max / past/future bounds; reopen resets drill-down to the committed month.

`DateTimeRange` supports the same `asString` behavior for start/end values and commits immediately (no OK button).

## Custom trigger

Use controlled `open` state to open `DateTime` from any button or input. For a popover beside the trigger, set `popover` and pass the trigger DOM element to `anchorEl`:

```tsx
function CustomDateTrigger() {
  const [open, setOpen] = useState(false);
  const [value, setValue] = useState<Date | null>(null);
  const [anchorEl, setAnchorEl] = useState<HTMLButtonElement | null>(null);

  return (
    <>
      <button ref={setAnchorEl} onClick={() => setOpen(true)}>
        {value ? value.toLocaleDateString() : "Choose a date"}
      </button>
      <DateTime
        mode="date"
        open={open}
        onOpenChange={setOpen}
        popover
        anchorEl={anchorEl}
        asString={false}
        value={value}
        onChange={(next) => setValue(next instanceof Date ? next : null)}
      />
    </>
  );
}
```

Leave out `popover` and `anchorEl` to render the picker as a centered modal.

## Theming

Override CSS variables (light defaults):

```css
:root {
  --ctp-primary: #7cb342;
  --ctp-primary-dark: #558b2f;
  --ctp-surface: #ffffff;
  --ctp-fg: #1f2937;
  --ctp-border: #e5e7eb;
  --ctp-focus: #7cb342;
  --ctp-danger: #dc2626;
  --ctp-z-index: 1000;
}
```

Dark theme: wrap with `data-ctp-theme="dark"` or pass `theme="dark"` for portaled popovers.

## Locales

Locales are per-instance (no global dayjs mutation). Import the dayjs locale before use:

```tsx
import "dayjs/locale/fr";
import { DateTime } from "universal-datetime-picker";

<DateTime locale="fr" weekStartsOn={1} inline onChange={console.log} />
```

## FAQ

### Is universal-datetime-picker a React date picker?

Yes. DateTime, DateTimeInput, and DateTimeRange are native React components on the main package entry. The same calendar core also ships as vanilla JS, Web Components, and thin Vue / Svelte / Angular registration helpers.

### Does it work without React?

Yes. Use universal-datetime-picker/vanilla for createDateTimePicker, or universal-datetime-picker/wc (and the CDN IIFE) for custom elements. React peers are optional when you stay on those entries.

### What is the support model for Solid and Preact?

Partial compatibility through Web Components only. There is no ./solid or ./preact package export. Register defineCustomElements from universal-datetime-picker/wc and render datetime-picker tags. Preact can also use preact/compat with the React entry if you prefer native React components.

### What does onChange return?

With asString omitted or false, date and datetime modes return a Date, and time mode returns a TimeValue object. Set asString to true for formatted strings. Date-only overlays commit on day click; datetime and time overlays commit when you press OK.

### What is the difference between inline, popover, and overlay?

Inline embeds the calendar in the page. Popover anchors the panel to an element (DateTimeInput always uses this). Overlay is a centered modal with a backdrop. Non-inline pickers default to open unless you set open or defaultOpen to false.

### Does DateTimeRange support popover anchoring?

No. DateTimeRange supports inline and modal open/close state, but it does not accept popover or anchorEl. Use a trigger button with open / onOpenChange if you need a closed-by-default range picker.

### How do locales work?

Pass a dayjs locale id such as fr or pt-br to the locale prop, and import that dayjs locale module first (for example import "dayjs/locale/fr"). Locale ids are dayjs module names, not arbitrary BCP-47 tags. UI chrome strings still use the labels prop.

### How do I use it from a CDN?

Load dist/style.css and dist/cdn/universal-datetime-picker.iife.js from jsDelivr or unpkg, then use <datetime-picker>, <datetime-picker-input>, or <datetime-picker-range>. Listen for the change CustomEvent; detail holds the selected value. Pin a version in production.

### Which package entry should I import?

universal-datetime-picker for React; ./vanilla for createDateTimePicker; ./wc for defineCustomElements; ./vue, ./svelte, or ./angular for registration helpers; ./core for headless controllers; ./style.css for styles.

### Is the calendar accessible?

Overlay pickers use dialog semantics, focus trapping, Escape to close, and arrow-key day navigation so keyboard and screen-reader users can select dates and times.

## Links

- [llms.txt](https://universal-datetime-picker.vercel.app/llms.txt)
- [Website](https://universal-datetime-picker.vercel.app/)
- [README](https://github.com/Bhardwaj-Raghav/universal-datetime-picker/blob/main/README.md)
- [npm](https://www.npmjs.com/package/universal-datetime-picker)
- [GitHub](https://github.com/Bhardwaj-Raghav/universal-datetime-picker)