React

Try the live React demo for interactive picker and copy-paste snippets.

Support tier

Full support. Native React components on the main package entry. No Web Components required. Peers: react and react-dom ≥ 18.

Install + deps

npm install universal-datetime-picker

Install React 18+ if your app does not already have it. Yarn and pnpm work the same.

Setup

Import the stylesheet once in your app entry or a shared layout. Then render DateTime, DateTimeInput, or DateTimeRange in any client React tree.

Exact import path

import DateTime, { DateTimeInput, DateTimeRange } from "universal-datetime-picker";
import "universal-datetime-picker/style.css";

Minimal example

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} />
    </>
  );
}

Realistic example

Controlled value and open state with a custom trigger. Pass popover and anchorEl to position beside the button.

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

function BookingForm() {
  const [open, setOpen] = useState(false);
  const [date, setDate] = useState<Date | null>(null);
  const [range, setRange] = useState<{
    start: Date | null;
    end: Date | null;
  }>({ start: null, end: null });
  const [anchorEl, setAnchorEl] = useState<HTMLButtonElement | null>(null);

  return (
    <>
      <button
        ref={setAnchorEl}
        type="button"
        onClick={() => setOpen(true)}
        aria-haspopup="dialog"
        aria-expanded={open}
      >
        {date ? date.toLocaleDateString() : "Choose a date"}
      </button>

      <DateTime
        mode="date"
        open={open}
        onOpenChange={setOpen}
        popover
        anchorEl={anchorEl}
        asString={false}
        value={date}
        onChange={(next) => setDate(next instanceof Date ? next : null)}
      />

      <DateTimeRange
        inline
        asString={false}
        value={range}
        onChange={setRange}
      />
    </>
  );
}

Configuration notes

Omit asString (or pass false) for Date / TimeValue objects. Set asString={true} for formatted strings.
Controlled: pass value + onChange. Uncontrolled: pass defaultValue.
Open state: open / defaultOpen + onOpenChange. Non-inline pickers default to open unless you set open or defaultOpen to false.
Date-only overlays commit on day click. Datetime and time overlays commit on OK.
TypeScript types ship with the package. Props are documented on Props.
DateTimeRange supports inline and modal open/close. It does not accept popover or anchorEl.

Events

onChange: selected value. Shape depends on mode and asString.
onOpenChange: overlay open/closed. Receives a boolean.

Customization links

Theming with CSS variables and dark mode
Locales via dayjs
Overlay and triggers
Full props reference

Pitfalls

Forgetting style.css leaves an unstyled calendar.
Non-inline DateTime without defaultOpen={false} or controlled open opens immediately on mount.
Importing from ./wc in a React app skips the native API. Prefer the main entry.
React 17 is not supported. Use React 18+ or a non-React entry.

Troubleshooting

Blank or broken UI usually means missing CSS, a wrong import path, or an SSR boundary issue in Next.js. See Troubleshooting and the Next.js guide.