forms / stable

DatePicker

Date field with typeable, locale-ordered segments and a calendar popover. DateRangePicker does periods.

LIVE PREVIEW

Loading preview…

When to use

Dates in forms and filters (due date, invoice date).
Periods — DateRangePicker.

Consider an alternative

An always-visible month — use Calendar.
Relative choices (“Next week”) — use Select.

Import

import { DatePicker } from '@revido-llc/kit';

Keyboard interaction

Ghost: Enter / Space / ↓ — open calendar and date fields
↑ / ↓ — change segment
Type digits — fill segment
← / → — move between segments
Enter in popover fields — done
Escape — close and return focus
Outline: Alt + ↓ — open calendar

Props

Props documented by the Kit. Refer to the TypeScript types for the complete interface, including inherited props.


className	string	—	Classes for the root (label + field + help).
controlClassName	string	—	Classes for the bordered field.
description	ReactNode	—	One short sentence of help under the control.
displayFormat	DisplayFormat	"numeric"	How the chosen date reads when the field isn't being edited. `numeric` (default): the typeable segments in locale order (dd-mm-jjjj in nl-NL). `month-day`: "Sep 26th, 2026" (ordinal suffix in English locales only). `day-month`: "26 Sep, 2026". Outline fields expose segments on focus; ghost controls open a popover containing the typeable segments.
emptyLabel	string	"Add date"	Empty ghost trigger text; typing is available inside the popover.
errorMessage	string \| ((validation: ValidationResult) => string)	—	Error text shown while the field is invalid (or a function of the validation result).
label	ReactNode	—	Visible label. Omit only when an `aria-label` names the field.
onCommit	((value: DateValue) => void)	—	Final value when ghost editing closes, including calendar selection and Clear.
size	FieldSize	"md"	`md` 32px (default) or `compact` 28px.
suffix	ReactNode	—	Quiet context inside the control, before its calendar action (for example Auto).
variant	"outline" \| "ghost"	"outline"	Outline form field or chip-less ghost value in a property rail.
autoComplete	string	—	Describes the type of autocomplete functionality the input should provide if any. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefautocomplete).
autoFocus	boolean	—	Whether the element should receive focus on render.
defaultValue	T	—	The default value (uncontrolled).
form	string	—	The `<form>` element to associate the input with. The value of this attribute must be the id of a `<form>` in the same document. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#form).
isDisabled	boolean	—	Whether the input is disabled.
isInvalid	boolean	—	Whether the input value is invalid.
isReadOnly	boolean	—	Whether the input can be selected but not changed by the user.
isRequired	boolean	—	Whether user input is required on the input before form submission.
name	string	—	The name of the input element, used when submitting an HTML form. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname).
onChange	((value: MappedDateValue<T>) => void)	—	Handler that is called when the value changes.
render	DOMRenderFunction<"div", DatePickerRenderProps>	—	Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: - You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). - Only a single root DOM element can be rendered (no fragments). - You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate.
validate	((value: MappedDateValue<T>) => ValidationError \| true)	—	A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if `validationBehavior="native"`. For realtime validation, use the `isInvalid` prop instead.
validationBehavior	"native" \| "aria"	'native'	Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA.
value	T	—	The current value (controlled).

Related exports

DateRangePicker

Examples

Dates and local timestamps

CalendarDateTime supplies time segments with minute granularity. Keep existing timestamp-to-local conversion in the app; use numeric display to retain the visible time.

import { DatePicker, parseDateTime, type CalendarDateTime } from "@revido-llc/kit";
// Preserve the app's timestamp ↔ local conversion; parseDateTime accepts no timezone suffix.
const value: CalendarDateTime | null = localValue ? parseDateTime(localValue) : null;
<DatePicker label="Introduction at" value={value} granularity="minute" hourCycle={24}
  onChange={(next) => persistLocalDateTime(next?.toString() ?? null)} />

Display formats

Shown when the field isn't being edited; focus it to type.

<DatePicker label="Due" displayFormat="month-day" defaultValue={parseDate("2026-09-26")} />

Range

<DateRangePicker label="Reporting period" value={range} onChange={setRange} />

Compact and invalid

<DatePicker aria-label="Start" size="compact" />
<DatePicker label="Deadline" minValue={start} errorMessage="Pick a date after the start." />

Static anatomy

A literal starting point; bind selection and validation in the consuming app.

<DateRangePicker label="Dates" />

Ghost rail values

Press the value to open date fields above the calendar. Clear or Done closes the popover; Escape returns focus.

<DatePicker aria-label="QA due" variant="ghost" emptyLabel="Add date" size="compact" suffix={<span className="text-2xs text-foreground-tertiary">Auto</span>} />
<DateRangePicker aria-label="Dates" variant="ghost" size="compact" />

Related components

Calendar ↗
RangeCalendar