Skip to content
View as Markdown

DatePicker ​

Three related components for date input — a segmented field, a field with a calendar popover, and a standalone calendar grid. Built on @internationalized/date and Base UI.

Import ​

tsx
import {
  DateField,
  DatePicker,
  DateRangePicker,
  Calendar,
  RangeCalendar,
  Field,
  useTimeZone,
  // Date value helpers (re-exported from @internationalized/date)
  parseDate,
  type CalendarDate,
  type DateValue,
  type DateRange,
} from "@tailor-platform/app-shell";

The examples below also import Button, Form, and Text from @tailor-platform/app-shell, and useId and useState from react.

API shape ​

DateField and DatePicker are standalone composite controls.

  • They own date entry, keyboard behavior, constraints, locale/timezone handling, and form value serialization.
  • They expose standard labeling hooks: id, aria-label, aria-labelledby, aria-describedby, and isInvalid.
  • They also auto-wire into Field.Root, so Field.Label, Field.Description, Field.Error, and form validation state work the same way as the other AppShell form controls.

DateField ​

Standalone usage with an accessible name:

tsx
function StandaloneDateField() {
  return <DateField aria-label="Invoice date" />;
}

With a visible label + description:

tsx
function LabeledDateField() {
  const id = useId();
  return (
    <div className="flex flex-col gap-2">
      <label id={`${id}-label`} htmlFor={id}>
        Invoice date
      </label>
      <DateField id={id} aria-labelledby={`${id}-label`} aria-describedby={`${id}-help`} />
      <Text.p id={`${id}-help`}>Format follows your locale</Text.p>
    </div>
  );
}

Inside Field.Root:

tsx
function DateFieldWithField() {
  return (
    <Field.Root name="invoiceDate">
      <Field.Label>Invoice date</Field.Label>
      <DateField />
      <Field.Description>Format follows your locale</Field.Description>
    </Field.Root>
  );
}

Controlled:

tsx
const [date, setDate] = useState<CalendarDate | null>(null);

<DateField aria-label="Invoice date" value={date} onChange={setDate} />;

DatePicker ​

A DateField with a calendar popover.

tsx
function StandaloneDatePicker() {
  return <DatePicker aria-label="Ship date" />;
}

Constrained + unavailable dates:

Use useTimeZone() to obtain today's date in AppShell's configured timezone, rather than calculating against the browser's timezone directly.

tsx
function ConstrainedDates() {
  const id = useId();
  const timeZone = useTimeZone();
  return (
    <div className="flex flex-col gap-2">
      <label id={`${id}-label`} htmlFor={id}>
        Delivery date
      </label>
      <DatePicker
        id={id}
        aria-labelledby={`${id}-label`}
        defaultValue={parseDate("2025-12-19")}
        minValue={timeZone.today()}
        isDateUnavailable={(date) => {
          const dow = date.toDate("UTC").getUTCDay();
          return dow === 0 || dow === 6;
        }}
      />
    </div>
  );
}

Week start:

tsx
function WeekStart() {
  return (
    <DatePicker
      aria-label="Date with Monday week start"
      defaultValue={parseDate("2025-12-19")}
      firstDayOfWeek="mon"
    />
  );
}

Validation and errors ​

Use standard HTML + ARIA when rendering the field standalone:

Click Check delivery date while empty to show a consumer-owned error, then choose a date to clear it. isInvalid and aria-describedby connect the standalone control to the visible message; useId keeps the association unique.

tsx
function StandaloneValidation() {
  const id = useId();
  const [date, setDate] = useState<DateValue | null>(null);
  const [checked, setChecked] = useState(false);
  const error = checked && !date ? "Choose a delivery date." : null;

  return (
    <div className="max-w-sm space-y-3">
      <label id={`${id}-label`} htmlFor={id}>
        Delivery date
      </label>
      <DatePicker
        id={id}
        aria-labelledby={`${id}-label`}
        aria-describedby={error ? `${id}-error` : undefined}
        isInvalid={!!error}
        value={date}
        onChange={setDate}
        placeholderValue={parseDate("2026-04-01")}
      />
      {error && (
        <Text.p id={`${id}-error`} role="alert">
          {error}
        </Text.p>
      )}
      <Button variant="outline" onClick={() => setChecked(true)}>
        Check delivery date
      </Button>
      <Text.p role="status">Selected date: {date?.toString() ?? "None"}</Text.p>
    </div>
  );
}

Or let Field.Root wire the label, description, and error elements:

Submit the empty field to see its required error. A date before April 1, 2026 can be typed, but the control's minValue validation blocks submission and surfaces through Field.Error match="customError". A valid date is submitted as an ISO date string; the result stays local.

tsx
function FieldValidation() {
  const [submitted, setSubmitted] = useState<{ deliveryDate: string } | null>(null);

  return (
    <Form<{ deliveryDate: string }>
      noValidate
      className="max-w-sm space-y-3"
      onFormSubmit={setSubmitted}
    >
      <Field.Root name="deliveryDate">
        <Field.Label>Delivery date</Field.Label>
        <DatePicker
          isRequired
          minValue={parseDate("2026-04-01")}
          placeholderValue={parseDate("2026-04-01")}
        />
        <Field.Description>
          Choose April 1, 2026 or later. Earlier dates can be typed, but not submitted.
        </Field.Description>
        <Field.Error match="valueMissing">Choose a delivery date.</Field.Error>
        <Field.Error match="customError" />
      </Field.Root>
      <Button type="submit">Save delivery date</Button>
      <pre role="status" className="overflow-x-auto text-sm">
        {submitted ? JSON.stringify(submitted, null, 2) : "No date submitted yet."}
      </pre>
    </Form>
  );
}

Calendar ​

A standalone calendar grid for custom date-selection UIs.

tsx
function StandaloneCalendar() {
  return (
    <Calendar
      aria-label="Select date"
      defaultValue={parseDate("2025-12-19")}
      onChange={(date) => console.log(date)}
    />
  );
}

DateRangePicker ​

Start and end segmented inputs sharing one calendar popover, with a { start, end } value (DateRange) — a separate component from DatePicker, not a mode. Same composition model as the other controls: standalone with aria-*, or inside Field.Root. Selection follows the react-aria model — the first calendar pick anchors the range and keeps the popover open, the highlight follows the pointer/arrows, and the second pick completes it; picking backwards swaps the endpoints, while a range typed in reverse is flagged invalid (Field.Error match="customError") rather than swapped.

The standalone controlled example keeps real DateRange values (DateValue endpoints), not strings. Choose two calendar days or edit the segments to see the complete range. Clear range resets both ends; a half-entered range reports null until both ends are complete. The clear action remounts the picker so incomplete drafts are reset even when the external value is already null.

tsx
function StandaloneDateRange() {
  const [resetKey, setResetKey] = useState(0);
  const [range, setRange] = useState<DateRange | null>({
    start: parseDate("2026-04-09"),
    end: parseDate("2026-04-12"),
  });

  return (
    <div className="max-w-md space-y-3">
      <DateRangePicker
        key={resetKey}
        aria-label="Billing period"
        value={range}
        onChange={setRange}
      />
      <Button
        variant="outline"
        onClick={() => {
          setRange(null);
          // Partial ranges already expose null, so remount to clear staged segments too.
          setResetKey((current) => current + 1);
        }}
      >
        Clear range
      </Button>
      <Text.p role="status">
        {range
          ? `Complete range: ${range.start.toString()} to ${range.end.toString()}`
          : "Choose both a start and an end date."}
      </Text.p>
    </div>
  );
}

Inside Form, the field owns the input value. Try submitting an empty range or only its start, then type an end date earlier than the start to see the built-in reversed-range error. Calendar selections normalize the endpoint order instead. Complete an ordered range to submit successfully.

onChange exposes a DateRange, while Form.onFormSubmit receives the combined serialized string, for example { "period": "2026-04-09/2026-04-12" }. The example displays that actual form payload without duplicating the input in string state.

tsx
function DateRangeWithField() {
  const [submitted, setSubmitted] = useState<{ period: string } | null>(null);

  return (
    <Form<{ period: string }> noValidate className="max-w-md space-y-3" onFormSubmit={setSubmitted}>
      <Field.Root name="period">
        <Field.Label>Billing period</Field.Label>
        <DateRangePicker isRequired placeholderValue={parseDate("2026-04-09")} />
        <Field.Description>
          Both dates are required. Type an end before the start to try the reversed-range error.
        </Field.Description>
        <Field.Error match="valueMissing">Choose both dates.</Field.Error>
        <Field.Error match="customError" />
      </Field.Root>
      <Button type="submit">Save billing period</Button>
      <pre role="status" className="overflow-x-auto text-sm">
        {submitted ? JSON.stringify(submitted, null, 2) : "No range submitted yet."}
      </pre>
    </Form>
  );
}

A single combined proxy input is registered as the one Field control — its value is empty until both ends are complete, so isRequired blocks a partial range. Give that combined input a name for a single start/end native-POST field (a wrapping Field.Root name wins), or use startName / endName to emit two plain hidden inputs for classic form-POST.

RangeCalendar ​

The standalone inline range calendar (the grid inside DateRangePicker), for custom layouts.

tsx
function StandaloneRangeCalendar() {
  return (
    <RangeCalendar
      aria-label="Stay dates"
      defaultValue={{ start: parseDate("2025-12-19"), end: parseDate("2025-12-23") }}
      onChange={(range) => console.log(range)}
    />
  );
}

Localization ​

Locale and timezone come from AppShell automatically. Override per field with locale / timeZone:

tsx
function LocalizedPicker() {
  return <DatePicker aria-label="Date" defaultValue={parseDate("2025-12-19")} locale="ja-JP" />;
}

Day of the week ​

showDayOfWeek adds the locale's short day of the week where the locale places it — 2025/12/19(金) for ja-JP, Fri, 12/19/2025 for en-US. It is read-only and derived from the entered date: it shows a placeholder until the date is complete, and while a date segment is mid-entry it keeps the previous day of the week (muted), so typing 25 into the day never flashes the 2nd's. Screen readers hear the full day name with each date segment's value.

tsx
function Weekday() {
  return (
    <DatePicker aria-label="Closing date" defaultValue={parseDate("2025-12-19")} showDayOfWeek />
  );
}

Keyboard ​

  • Segments: ↑/↓ increment/decrement, digits type-to-fill (auto-advance), ←/→ move between segments, Backspace clears, / commits the current segment and advances.
  • Whole-date shortcuts: t today · m/h start/end of the entered month · y/r start/end of the year · w/k start/end of the week · - previous day · =/+ next day.
  • Calendar grid: arrows move by day/week, Home/End to week start/end, PageUp/PageDown by month, Shift+PageUp/PageDown by year, Enter/Space selects. Alt+↓ opens the calendar from the field.

Props ​

DateFieldProps ​

PropTypeDescription
value / defaultValueDateValue | nullControlled / uncontrolled value
onChange(v: DateValue | null) => voidFires when the value changes
onBlur() => voidFires when focus leaves the whole segmented control
minValue / maxValueDateValueInclusive date range bounds
isDateUnavailable(date: DateValue) => booleanMarks specific dates unavailable
isDisabledbooleanDisables interaction and form submission
isReadOnlybooleanAllows focus/navigation without editing
isRequiredbooleanMarks the control required
isInvalidbooleanAdds invalid styling / aria-invalid to the segmented UI
placeholderValueDateValueSeeds unset segments
granularity"day" | "hour" | "minute" | "second"Smallest editable unit; time granularities add time segments
hourCycle12 | 24Force 12- or 24-hour time; defaults to the locale
autoFocusbooleanFocus the first segment on mount
localestringBCP-47 locale override
showDayOfWeekbooleanShow the locale's short day of the week next to the date
namestringEmits a form value through the proxy input
idstringProxy input id (use with external <label htmlFor>).
firstDayOfWeek"sun" | "mon" | "tue" | "wed" | "thu" | "fri" | "sat"Override the locale week start used by w / k shortcuts
aria-label / aria-labelledbystringAccessible name
aria-describedbystringIDs of description / error elements
classNamestringRoot element class

DatePickerProps ​

All DateFieldProps, plus:

PropTypeDescription
timeZonestringIANA timezone for resolving "today"
firstDayOfWeek"sun" | "mon" | ...Force the calendar's first column

CalendarProps ​

See the calendar docs in-code: controlled/uncontrolled value, min/max, unavailable dates, focused date, locale, timezone, accessible naming, and className.

DateRangePickerProps ​

The DatePickerProps surface (labeling, isInvalid, min/maxValue, isDateUnavailable, granularity, hourCycle, firstDayOfWeek, timeZone, locale, showDayOfWeek, autoFocus, isDisabled/ReadOnly/Required), with the range-specific differences:

PropTypeDescription
value / defaultValueDateRange | nullControlled / uncontrolled { start, end } range
onChange(v: DateRange | null) => voidFires with a complete range, or null when cleared/incomplete
namestringOne combined hidden input (start/end) for native POST; Field.Root name wins
startName / endNamestringEmit two plain hidden inputs with the ISO start/end (classic POST)

A typed range with end before start sets the invalid state and reports a built-in customError message (Field.Error match="customError"); the calendar always commits ordered endpoints.

RangeCalendarProps ​

Same surface as CalendarProps, with value / defaultValue: DateRange | null and onChange: (v: DateRange) => void (fired once per selection, when the second date completes the range).

The optional onSelectionStateChange receives a discriminated event for each selection transition:

event.typeAdditional payloadMeaning
selection-start—The first pick anchors an unfinished range
range-completevalue: DateRangeThe second pick completes an ordered range
selection-cancel—Escape cancels an unfinished selection

Use these events to disable external Apply actions until selection completes or is cancelled. Only range-complete carries a value; it contains the same range passed to the existing onChange, so event-only consumers do not need to subscribe to both callbacks. Events report interactions only, not initial render or unmount; when resetting or remounting the calendar, reset any parent-owned selection state too.