Skip to content

Date Picker

⋯

Date Picker renders either labeled ISO date inputs with an inline calendar, or a bare calendar for composition inside a Popover. The approved Figma frames define 304 × 388 px for a single date and 836 × 456 px for a range with presets. The range calendar adapts to its container width. In calendar presentation, single and multiple modes are 280 px wide. Inside 12 px padding, the frame is 304 px wide, the width of the Figma Date Picker. Editable controls use the same Input styling as other Nesra form fields.

In field presentation, selecting a day or preset changes a draft. Apply commits it and calls onValueChange; Cancel restores the last committed value. Calendar presentation commits a single date, completed range, preset, or multiple-date toggle immediately. The component does not open a popover itself.

import { DatePicker } from "@nesra/ui/date-picker";
export function AppointmentDate() {
return <DatePicker label="Appointment date" name="appointment" />;
}

The root import @nesra/ui also exports Date Picker and its types.

For an application-controlled range, keep the committed value in state. onValueChange receives the value only after Apply:

import { useState } from "react";
import { DatePicker, type DateRange } from "@nesra/ui/date-picker";
export function ReportPeriod() {
const [period, setPeriod] = useState<DateRange | null>(null);
return (
<DatePicker
mode="range"
label="Report period"
timeZone="Asia/Jakarta"
value={period}
onValueChange={setPeriod}
/>
);
}

Compose Date Picker with Popover when the calendar should open from a compact trigger. presentation="calendar" removes the field and duplicate panel surface. The controlled callback updates the trigger and closes the popup as soon as the user selects a date.

For a range, timeZone is required to resolve Today, Yesterday, week and month, rolling-day, and Since presets. The Since… action asks for a start date and uses today in that time zone as its inclusive end date. In calendar presentation, the second date or a preset commits the range and can close the Popover.

mode="multiple" toggles each clicked date and marks every chosen date as selected. It requires presentation="calendar" because the field’s ISO text inputs hold one date or one range. onValueChange receives the ascending, de-duplicated dates after each toggle.

hideNavigation removes the month buttons and the month and year selects. Set minDate and maxDate to the month that the page chose elsewhere. When those limits move to another month, the calendar shows the new month.

Selected dates · 3

  • 03 Oct 2026
  • 10 Oct 2026
  • 17 Oct 2026

The page owns the list of chosen dates, so a removable Badge can remove a date from the same state.

Use the default field presentation when editable ISO input and explicit Apply/Cancel actions are part of the workflow.

Selected: 2026-08-20

Presets

Custom range

Choose August 15–31. August 25 is unavailable.

A range cannot include a date disabled by minDate, maxDate, or isDateDisabled.

Select August 15–31, except August 25.

The error prop displays an associated application validation alert in place of description. Invalid typed dates produce a component alert. Date inputs accept only YYYY-MM-DD. Input edits remain uncommitted until Apply.

locale formats month, weekday, and date announcements. weekStartsOn overrides the locale’s first day of the week. The input format and calendar action labels remain in English.

Presets

Custom range

name submits the committed date. Range fields use name[start] and name[end]. Multiple mode submits one name entry per selected date, in ascending order. Disabled fields submit no value. Native form submission is blocked while the displayed text differs from the committed value.

Date picker follows the page theme through .dark or data-theme="dark". The roles follow Figma’s Date Picker and .Date Item components.

Part Figma variable CSS token
Panel Surface/card-bg-neutral, 1px Stroke/stroke-border --nesra-surface-card-bg-neutral, --nesra-stroke-border
Panel shadow Box Shadow/shadow-lg shadow-nesra-lg
Selected date or range end Action/primary-default, Text/text-on-brand --nesra-action-primary-default, --nesra-text-on-brand
Dates inside a range Foundation/bg-disabled, Text/text-tertiary --nesra-foundation-bg-disabled, --nesra-text-tertiary
Today 1px Stroke/stroke-brand-primary, no fill --nesra-stroke-brand-primary
Outside days, weekday names Text/text-support --nesra-text-support
Presets label, range heading Text/text-support --nesra-text-support
Unavailable dates Text/text-disabled --nesra-text-disabled
Day focus Box Shadow/Focus ring shadow-nesra-focus-ring

In Dark the selected date becomes a light fill with dark text, so its label stays readable. Both the single and range panels have the 1px border, 12px and 16px radius respectively. The bare calendar (presentation="calendar") has no panel surface, border, or shadow.

  • The calendar is visible below enabled inputs. The consuming page chooses a meaningful label, validates any business rule beyond the selectable-date limits, and decides when to show error.
  • Day buttons have full localized date names. Arrow keys move one day or week. Home and End move to the week’s edge. Page Up and Down move one month. Shift plus Page Up or Down moves one year. Shift plus an arrow key extends a range from its starting date.
  • In multiple mode, Enter or Space toggles the focused date. Each selected date’s grid cell has aria-selected="true". With hideNavigation, set minDate and maxDate to keep arrow keys, Page Up, and Page Down inside the shown month.
  • Disabled dates cannot receive focus or be selected. Each calendar grid has a month and year name, and selected dates are marked on their grid cells. Explain any application-specific disabled-date rule near the control.
  • The range panel shows two months when its container is at least 700 px wide. Presets stay to the left at widths of at least 520 px. In narrower containers, a preset select appears above a single month.
Prop Type Default Effect
mode "single" | "range" | "multiple" "single" Selects one ISO date, an inclusive { start, end } range, or separate dates.
presentation "field" | "calendar" "field" Renders the full field or a bare calendar. Multiple mode requires "calendar".
hideNavigation boolean false Hides month buttons and month and year selects. Follows minDate and maxDate.
value string | null (single), DateRange | null (range), or string[] (multiple) — Controls the committed selection.
defaultValue string | null (single), DateRange | null (range), or string[] (multiple) null, or [] in multiple mode Sets the initial uncontrolled selection.
onValueChange (value: string | null) => void, (value: DateRange | null) => void, or (value: string[]) => void — Receives a valid applied or calendar-completed value.
label string required Visible label and accessible field name.
name string — Submits a single ISO date, name[start] and name[end], or one entry per date.
timeZone IANA time zone string local zone in single, required in range Resolves relative presets and Today without converting selected values to instants.
locale BCP 47 locale string "en-US" Formats date announcements and month/weekday labels.
weekStartsOn 0–6 (Sunday–Saturday) locale’s first day Overrides the calendar and week presets.
minDate, maxDate ISO date string — Inclusive selectable limits.
isDateDisabled (date: string) => boolean — Disables dates, including dates inside a proposed range.
ref, inputRef Ref<HTMLInputElement> — Reference the first editable date input.
required, disabled boolean false Require input or disable editing and form submission.
error, description string — Show an associated error alert or helper text. Error replaces description.
id string generated Identifies the first input and its label.
className string — Adds classes to the Date Picker root.

DateRange is { start: string; end: string }, with both dates in YYYY-MM-DD format. The package also exports DatePreset and DATE_PRESETS from the root and @nesra/ui/date-picker. DATE_PRESETS contains the identifiers today, yesterday, this-week, this-month, last-week, last-month, last-7-days, last-14-days, last-30-days, last-365-days, and since. Preset selection is available in range mode.

The public values are date-only strings. Consumers that need an instant must choose a time and time zone in their application. Styling uses colors, layout, and shape and elevation tokens.