Date Picker

Installation

$ npx @grampro/kit add DatePicker

The block copies the date-picker folder into your project, along with the small shared folder that every component imports. You own the code and can change it freely. The files land in component-lib/, or src/component-lib/ when your project has a src/ folder; pass --dest to put them somewhere else, and later installs follow the first. There are no peer dependencies other than React.

Requirements

• React 19 and @types/react 19
• TypeScript target ES2022 or newer, with "jsx": "react-jsx"
• Browsers from 2024 or newer (the styles use light-dark(), :has() and the Popover API)

Import the stylesheet once, for example in your global CSS:

@import "../component-lib/gbs.css";

or in your root layout / entry file:

import "@/component-lib/gbs.css";

DatePicker selects one date, DateRangePicker a start and an end, and DateTimePicker a date with a time of day. Each is a text field plus a calendar: people can type a date in their own date order or pick one, and the whole calendar works from the keyboard. They share one engine, one stylesheet and one set of keyboard rules. The calendar renders in the browser's top layer, so it is never clipped by a scrolling parent — including inside a DataGrid cell.

DatePicker

DateRangePicker

Quick Start

"use client";
 
import { useState } from "react";
import {
  DatePicker,
  DateRangePicker,
  type DateRange,
} from "@/component-lib/date-picker";
 
export default function Example() {
  const [date, setDate] = useState<Date | null>(null);
  const [range, setRange] = useState<DateRange>({ start: null, end: null });
 
  return (
    <>
      <DatePicker label="Delivery date" value={date} onChange={setDate} />
 
      <DateRangePicker
        label="Reporting period"
        value={range}
        onChange={setRange}
      />
    </>
  );
}

Both components are controlled with value + onChange, or uncontrolled with defaultValue. The range picker also reports whether the range is finished:

<DateRangePicker onChange={(range, complete) => complete && refetch(range)} />

Values and Formatting

value, defaultValue, min and max accept a Date, an ISO yyyy-mm-dd string or a timestamp. onChange always gives back Date objects.

type DateInput = Date | string | number;
 
interface DateRange {
  start: Date | null;
  end: Date | null;
}

Every date is a local date at midnight, so a day never shifts across time zones. ISO strings are read as local days, not UTC — the mistake behind "my date is one day off" bugs.

The field's text comes from format, which takes Intl options or your own function:

<DatePicker format={{ dateStyle: "medium" }} />
<DatePicker format={(date) => date.toISOString().slice(0, 10)} />

Store values with toISODate(date) (from the same package) rather than toISOString(), which converts to UTC first.

Props Table

Shared

DatePicker

DateRangePicker

DateTimePicker

Takes the shared props, with min / max as moments, plus:

Typed Entry

People can type instead of picking, and the calendar follows along as they type.

• Numbers are read in the locale's own field order: 03/04/2026 is 3 April in en-GB and 4 March in en-US.
• ISO (2026-03-12) is accepted in every locale.
• Month names work, long or short: 12 Mar 2026, March 12, 2026.
• A missing year falls back to the year on screen, and a lone number is a day in the visible month: 15/8 and 5.
• Two-digit years use the usual pivot: 26 is 2026, 95 is 1995.
• Separators are free: /, -, . or spaces.

Text that isn't a date, or a date outside min / max, shows a message when the field loses focus and leaves the value untouched. Set allowInput={false} for a pick-only field.

Type a date or pick one. Field order, month names and the first day of the week follow the locale, while ISO and written months (“12 Mar 2026”) are always accepted.

Limits and Blocked Days

<DatePicker
  min="2026-01-01"
  max={new Date(2026, 11, 31)}
  isDateDisabled={(day) => day.getDay() === 0 || day.getDay() === 6}
/>

min / max stop the arrows, the month and year panels and typed entry. isDateDisabled blocks individual days: they stay visible but cannot be chosen. Keep the function stable (module level or useMemo) so the months are not rebuilt on every render.

A bookable window with weekends blocked, week numbers on and the week starting on Sunday.

Date and Time

const [meeting, setMeeting] = useState<Date | null>(null);
 
<DateTimePicker
  label="Meeting"
  value={meeting}
  onChange={setMeeting}
  min="2026-03-15T09:00"
  minuteStep={15}
  defaultTime="09:00"
/>;

DateTimePicker adds a time row under the calendar: the hour, the minute and, with showSeconds, the second, each a spin button the arrow keys step. On a 12-hour clock there is an AM/PM switch. The clock follows locale — 2:30 PM in en-US, 14:30 in en-GB — unless hourCycle says otherwise.

• The value is wall-clock time. onChange gives a Date in local time; no time zone is chosen or converted. name posts yyyy-mm-ddTHH:mm, the shape a native datetime-local input posts.
• min and max are moments, not days. Earlier days cannot be picked, and on the first allowed day an earlier time is moved up to min.
• Picking a day keeps the time already chosen. Before any time is set, a picked day takes defaultTime (00:00 unless given). The calendar stays open after a day is picked, since the time usually comes next; Enter in the time row, or Escape, closes it.
• Typing works too: a date in the locale's order followed by a time — 15/03/2026 14:30, Mar 15, 2026, 2:30 PM — and ISO 2026-03-15T14:30 everywhere.

A meeting scheduler with 15-minute steps and a bounded window, and a 24-hour field with seconds.

Range Presets

import {
  addDays,
  startOfMonth,
  type DatePreset,
} from "@/component-lib/date-picker";
 
const presets: DatePreset[] = [
  {
    label: "Last 7 days",
    range: { start: addDays(new Date(), -6), end: new Date() },
  },
  {
    label: "This month",
    range: { start: startOfMonth(new Date()), end: new Date() },
  },
];
 
<DateRangePicker presets={presets} value={range} onChange={setRange} />;

Picking a range takes two clicks: the first sets the start, the second the end, with a preview band in between. Clicking in reverse order is fine — the range is put the right way round. A third click starts a new range.

Two months side by side, presets down the edge, and the preview band that follows the cursor while the second date is still open.

Forms

With a name, the value posts as a hidden input so FormData and server actions pick it up. Dates post as yyyy-mm-dd; the range posts two fields:

<form
  onSubmit={(event) => {
    event.preventDefault();
    const data = new FormData(event.currentTarget);
    console.log(data.get("invoice")); // "2026-03-12"
    console.log(data.get("period-start"), data.get("period-end"));
  }}
>
  <DatePicker name="invoice" label="Invoice date" required error={error} />
  <DateRangePicker name="period" label="Period" />
  <button type="submit">Save</button>
</form>

error shows a message below the control, colors the border and sets aria-invalid. Validation is yours; the component only displays the state.

Uncontrolled fields posting ISO dates through hidden inputs — the range posts period-start and period-end.

Imperative API (ref)

const picker = useRef<DatePickerHandle<Date | null>>(null);
 
<DatePicker ref={picker} />;
 
picker.current?.open();

Keyboard

Accessibility: each month is a table role="grid" where only the focused day is tabbable, which is the WAI-ARIA pattern for a date picker. Days carry a full spoken label ("Thursday, 12 March 2026"), today is aria-current="date", selected days are aria-selected, and the calendar is a role="dialog" labelled by calendarLabel. Changes are announced through a status region.

Styling and Theming

Rules ship unlayered, so a framework reset cannot strip them and a utility class passed through className still overrides them. Import the generated gbs.css once — see Theming.

<DatePicker
  className="max-w-sm"
  classNames={{ control: "shadow-sm", day: "font-mono" }}
/>

CSS variables

Override them on .dp-root, on any ancestor, or through style. Each variable falls back to the shared --gbs-* of the same name, then to the DataGrid's --dg-* when that stylesheet is loaded, and finally to the built-in palette.

.dp-root {
  --dp-accent: #7c3aed;
  --dp-day-size: 38px;
}

Dark mode

Colors follow the page's color-scheme. To force a scheme, put class="dark" or data-theme="dark" (or "light") on an ancestor such as <html>.

Data attributes

Locale Text

<DatePicker
  localeText={{
    today: "Heute",
    clear: "Löschen",
    invalidDate: "Bitte ein gültiges Datum eingeben",
  }}
/>

Month names, weekday names, the typing order and the first day of the week come from locale, not from localeText.

Core Exports

useDatePicker() holds the whole engine — selection, the visible months, typed input, keyboard movement and the popover state — and is exported for building a different UI on the same behavior:

const controlRef = useRef<HTMLDivElement>(null);
const triggerRef = useRef<HTMLButtonElement>(null);
 
const picker = useDatePicker({
  range: false,
  defaultValue: { start: null, end: null },
  onSelectionChange: (next) => …,
  min: null,
  max: null,
  numberOfMonths: 1,
  fixedWeeks: true,
  disabled: false,
  readOnly: false,
  closeOnSelect: true,
  text: defaultDatePickerText,
  controlRef,
  triggerRef,
});

It returns open, view, months, weekdays, years, title, focusedDate, selection, selectDate, applyRange, clear, goToToday, goToMonth, goToYear, selectMonth, selectYear, onGridKeyDown, getDayState, inputValue, onInputChange, onInputBlur, inputError, onTriggerClick and onPopoverClose.

The framework-free helpers are exported from @/component-lib/date-picker/core and can also run on a server:

Next.js

The components are client components: "use client" is already at the top of the files that need it. The core folder imports nothing from React, so a Server Component or a route handler can build months, parse and format dates with the same code.

Pass locale when the page is rendered on the server, so the server and the browser produce the same text on the first paint.

Today's date is never part of the server's HTML. The server and the browser can sit on opposite sides of midnight, or in different time zones, so a day marked on the server is a day the browser might disagree with. The calendar therefore renders with no data-today until hydration has finished, and marks the day in the render straight after — which costs nothing visible, because the calendar lives in a popover the user has to open first. A page with no server rendering marks it on the very first pass.

The same value updates itself at the next local midnight, so a dashboard left open overnight does not go on pointing at yesterday. One timer serves every picker on the page. To pin the date in a test, pass today to the core helpers (buildMonth, buildMonths); null marks no day at all.

Migrating from the Previous DatePicker

Notes

• Dates only: no time-of-day or time-zone picking. Values are local midnight.
• One range per field; several disjoint ranges are not supported.
• The Gregorian calendar only, though month and weekday names, the field order and the first day of the week all follow locale.