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} /> );}Examples
Section titled “Examples”Single date with popover
Section titled “Single date with popover”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.
import { Button } from "@nesra/ui/button";import { DatePicker } from "@nesra/ui/date-picker";import { Popover } from "@nesra/ui/popover";import { CalendarDays } from "lucide-react";import { useState } from "react";
function formatDate(value: string | null) { if (!value) return "Pick a date";
const [year, month, day] = value.split("-").map(Number); return new Intl.DateTimeFormat("en-US", { dateStyle: "medium", timeZone: "UTC" }).format( new Date(Date.UTC(year!, month! - 1, day)), );}
export function DatePickerPopoverExample() { const [date, setDate] = useState<string | null>(null); const [open, setOpen] = useState(false);
return ( <Popover open={open} onOpenChange={setOpen}> <Popover.Trigger render={ <Button className="w-[280px] justify-start" startIcon={<CalendarDays />} variant="outline" /> } > {formatDate(date)} </Popover.Trigger> <Popover.Content align="start" className="w-[304px] p-nesra-padding-xl"> <Popover.Title className="sr-only">Choose an appointment date</Popover.Title> <DatePicker label="Appointment date" presentation="calendar" value={date} onValueChange={(value) => { setDate(value); setOpen(false); }} /> </Popover.Content> </Popover> );}Range and presets with popover
Section titled “Range and presets with popover”import { Button } from "@nesra/ui/button";import { DatePicker, type DateRange } from "@nesra/ui/date-picker";import { Popover } from "@nesra/ui/popover";import { CalendarDays } from "lucide-react";import { useState } from "react";
function formatDate(value: string) { const [year, month, day] = value.split("-").map(Number); return new Intl.DateTimeFormat("en-US", { month: "short", day: "numeric", timeZone: "UTC", }).format(new Date(Date.UTC(year!, month! - 1, day)));}
function formatRange(value: DateRange | null) { if (!value) return "Pick a date range"; return `${formatDate(value.start)} – ${formatDate(value.end)}`;}
export function DatePickerPopoverRangeExample() { const [period, setPeriod] = useState<DateRange | null>({ start: "2026-08-03", end: "2026-08-09", }); const [open, setOpen] = useState(false);
return ( <Popover open={open} onOpenChange={setOpen}> <Popover.Trigger render={ <Button className="w-[280px] justify-start" startIcon={<CalendarDays />} variant="outline" /> } > {formatRange(period)} </Popover.Trigger> <Popover.Content align="start" className="w-[836px] p-nesra-padding-xl"> <Popover.Title className="sr-only">Choose a reporting period</Popover.Title> <DatePicker label="Reporting period" mode="range" presentation="calendar" timeZone="Asia/Jakarta" value={period} onValueChange={(value) => { setPeriod(value); setOpen(false); }} /> </Popover.Content> </Popover> );}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.
Multiple dates in a fixed month
Section titled “Multiple dates in a fixed month”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.
import { Badge } from "@nesra/ui/badge";import { DatePicker } from "@nesra/ui/date-picker";import { Trash2 } from "lucide-react";import { useState } from "react";
function formatDate(value: string) { const [year, month, day] = value.split("-").map(Number); return new Intl.DateTimeFormat("en-GB", { day: "2-digit", month: "short", year: "numeric", timeZone: "UTC", }).format(new Date(Date.UTC(year!, month! - 1, day)));}
export function DatePickerMultipleExample() { const [dates, setDates] = useState<string[]>(["2026-10-03", "2026-10-10", "2026-10-17"]);
return ( <div className="flex flex-wrap items-start gap-nesra-spacing-xl"> <div className="rounded-nesra-xl border border-nesra-stroke-border p-nesra-padding-xl"> <DatePicker label="Campaign dates" mode="multiple" presentation="calendar" hideNavigation minDate="2026-10-01" maxDate="2026-10-31" name="campaignDates" value={dates} onValueChange={setDates} /> </div> <div className="grid max-w-80 gap-nesra-spacing-md"> <p className="type-nesra-body-small-regular text-nesra-text-support"> Selected dates · {dates.length} </p> <ul className="flex flex-wrap gap-nesra-spacing-md"> {dates.map((date) => ( <li key={date}> <Badge color="neutral" endIcon={<Trash2 />} onRemove={() => setDates((current) => current.filter((item) => item !== date))} > {formatDate(date)} </Badge> </li> ))} </ul> </div> </div> );}The page owns the list of chosen dates, so a removable Badge can remove a date from the same state.
Inline field
Section titled “Inline field”Use the default field presentation when editable ISO input and explicit Apply/Cancel actions are part of the workflow.
import { DatePicker } from "@nesra/ui/date-picker";import { useState } from "react";
export function DatePickerSingleExample() { const [date, setDate] = useState<string | null>("2026-08-20");
return ( <div className="grid w-full max-w-xl gap-nesra-spacing-sm"> <DatePicker label="Appointment date" value={date} onValueChange={setDate} /> <p>Selected: {date ?? "None"}</p> </div> );}Range with unavailable dates
Section titled “Range with unavailable dates”import { DatePicker } from "@nesra/ui/date-picker";
export function DatePickerRangeDisabledExample() { return ( <div className="w-full max-w-[836px]"> <DatePicker label="Booking period" mode="range" timeZone="Asia/Jakarta" defaultValue={{ start: "2026-08-20", end: "2026-08-22" }} minDate="2026-08-15" maxDate="2026-08-31" isDateDisabled={(date) => date === "2026-08-25"} description="Choose August 15–31. August 25 is unavailable." /> </div> );}A range cannot include a date disabled by minDate, maxDate, or isDateDisabled.
Disabled dates and validation
Section titled “Disabled dates and validation”import { DatePicker } from "@nesra/ui/date-picker";
export function DatePickerValidationExample() { return ( <div className="grid w-full max-w-xl gap-nesra-spacing-lg"> <DatePicker label="Available date" defaultValue="2026-08-20" minDate="2026-08-15" maxDate="2026-08-31" isDateDisabled={(date) => date === "2026-08-25"} description="Select August 15–31, except August 25." required /> <DatePicker label="Review date" error="Choose a date before continuing." /> <DatePicker label="Archived date" defaultValue="2026-08-20" disabled /> </div> );}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 and week start
Section titled “Locale and week start”import { DatePicker } from "@nesra/ui/date-picker";
export function DatePickerLocaleExample() { return ( <div className="w-full max-w-xl"> <DatePicker label="Tanggal janji" defaultValue="2026-08-20" locale="id-ID" weekStartsOn={1} /> </div> );}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.
Form submission
Section titled “Form submission”import { Button } from "@nesra/ui/button";import { DatePicker } from "@nesra/ui/date-picker";import { useState } from "react";
export function DatePickerFormExample() { const [submitted, setSubmitted] = useState<string | null>(null);
return ( <form onSubmit={(event) => { event.preventDefault(); const fields = Object.fromEntries(new FormData(event.currentTarget)); setSubmitted(JSON.stringify(fields, null, 2)); }} className="grid w-full max-w-xl gap-nesra-spacing-lg" > <DatePicker label="Appointment date" name="appointment" required /> <DatePicker label="Reporting period" mode="range" timeZone="Asia/Jakarta" name="period" /> <Button type="submit">Submit dates</Button> {submitted && <pre aria-live="polite">{submitted}</pre>} </form> );}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.
Light and Dark
Section titled “Light and Dark”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.
Accessibility
Section titled “Accessibility”- 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 showerror. - 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". WithhideNavigation, setminDateandmaxDateto 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.
API reference
Section titled “API reference”| 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.