Date Picker

Installation

npx gbs-add-block@latest -a DatePicker -beta

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. 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 "../components/date-picker/styles.css";

or in your root layout / entry file:

import "@/components/date-picker/styles.css";

DatePicker selects one date and DateRangePicker selects a start and an end. Both are 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 "@/components/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

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.

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.

Range Presets

import {
  addDays,
  startOfMonth,
  type DatePreset,
} from "@/components/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.

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.

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

All rules are in the CSS components layer, so utility classes passed through className / classNames override them.

<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.

Headless Use

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 @/components/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.

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.