Date / time picker

Preview

Local preview. It doesn't affect real accounts, environments, or run data.

Usage

Enter a date, date range, or time in a locale format, or pick one from a calendar. It composes React Aria's segmented input, calendar grid, and range selection on the shared form surface. DateLocaleProvider sets the locale format. The examples cover Korean, English, and RTL. Min and max, unavailable dates, required values, form submission, and reset are validated.

• Don't interchange date types. Use CalendarDate for calendar dates, CalendarDateTime for local date-times, ZonedDateTime for instants, and Time for wall-clock times.
• Don't convert date-only values to UTC midnight. Keep them as CalendarDate.
• Don't store real execution times without an IANA time zone and an explicit DST policy.
• Don't pick earlier or later on the user's behalf for an ambiguous or nonexistent local time. By default, the examples reject these times.
• Don't treat this library as a replacement for Temporal or server-side schedule and permission validation.
• Don't mutate date objects or mix their types. Keep them immutable and of the same type.
• Don't expect form reset to restore controlled values. Reset them yourself in onReset.

Size: SizeProvider size="small" resizes the whole composition, including portals. The default size is Default. Size guidance and comparisons

Anatomy

DateLocaleProvider → DatePicker / DateRangePicker / TimeField → Label + Group + DateInput segments + calendar trigger → Popover + Dialog + Calendar/RangeCalendar → month navigation + weekday headers + grid cells; description + FieldError

Keyboard and accessibility

• Tab, Shift+Tab, and the Left and Right arrow keys move between segments.
• Type digits to fill a segment. Up and Down increment and decrement it, and Home, End, Backspace, and Delete edit it.
• In the calendar, arrow keys move by day, and Page Up and Page Down move by month. Shift+Page Up and Shift+Page Down move by year.
• Enter or Space on the calendar button opens the calendar. In the calendar, Enter or Space selects a date, or the start and end of a range.
• Escape closes the calendar and returns focus to the trigger.
• Disabled values can't be edited. Read-only values can be navigated and read, but not changed.
• The popup avoids collisions, and touch selection works.
• Each date and time segment is a spinbutton.

Give each control a name that describes its purpose. Connect error messages to their controls, and signal state with more than color. Automated checks don't replace manual keyboard and assistive technology testing.

Example code

Shared components take their styles from design tokens. Each example sets its own composition and accessibility attributes. The calling screen defines callbacks, refs, and product data.

// Needs React Aria Components: npm install react-aria-components
import {
  DatePicker,
  DateRangePicker,
  TimeField,
  DateLocaleProvider,
} from '@surflane/ui/date-picker'
import {
  parseDate,
  parseDateTime,
  Time,
  toZoned,
} from '@internationalized/date'

<DateLocaleProvider locale='en-US'>
  <DatePicker
    label='Run date'
    name='runDate'
    value={date}
    onValueChange={setDate}
    minValue={parseDate('2026-10-01')}
    maxValue={parseDate('2026-12-31')}
    required
    description='October–December 2026'
  />
  <DateRangePicker
    label='Release window'
    startName='from'
    endName='to'
    value={range}
    onValueChange={setRange}
  />
  <TimeField
    label='Start time'
    name='time'
    defaultValue={new Time(9, 30)}
    hourCycle={24}
  />
</DateLocaleProvider>

// A local time is not an instant. Resolve explicitly and handle rejection.
try {
  const instant = toZoned(
    parseDateTime('2026-11-01T01:30'),
    'America/New_York',
    'reject',
  )
  console.log(instant.toAbsoluteString())
} catch {
  /* Ask for another time or an explicit earlier/later decision. */
}
// Controlled form reset: explicitly restore date/range state in onReset.

Key API

The table lists the common wrapper's main props. See the package type declarations for the full types.

Related tokens