DatePicker

Usage

• Use DatePicker when the value is a point or period on the calendar, such as a send date, a scheduled time, or the period a report covers.
• Use DatePicker with presets to filter reports and activity by date range.
• Limit the calendar to the dates the user can choose (minDate, maxDate, isDateDisabled). Never allow any date and report the problem afterward with an error.
• Disable dates after today on reporting filters (maxDate).
• Provide a visible label (label) that describes what the date represents.
• Provide an accessible label (ariaLabel) in place of a visible label only when the DatePicker sits in a toolbar or filter row where a visible label competes with the surrounding controls.
• Never use a placeholder in place of a visible label.
• Use a single range DatePicker (isRange) when the user needs both a start and an end date. Never split a required period across two DatePickers.
• Reserve two separate single-date DatePickers for filters where either end is optional.

Types

• Date — the default. Selects a single date.
• Date range (isRange) — selects a start date and an end date.
• Date and time (withTime) — selects a single moment in a chosen time zone.
• Date and time range (isRange with withTime) — selects a start and end moment. Use for the most granular timeframes.

Appearance

• Presets (withPresets) — a list of common periods beside the calendar, available on range types only. Show presets wherever users return to the same periods often.
• No presets — omit withPresets for ranges that rarely repeat; the popover shows only the calendar.
• Medium (size="md") — the default, suitable for most forms.
• Small (size="sm") — for toolbars and filter rows where the DatePicker sits beside other small controls.

Behaviors

• Base, hover, focus, and active states follow standard form-control styling. Focus adds the standard 2px focus ring and updates the border color. Active styling applies while the popover is open.
• Disabled state (isDisabled) — blocks interaction and updates the background and text color.
• Critical state (isInvalid with error) — applies critical styling and renders the error message below the field.
• Clear button (isClearable with onClear) — resets the selection. Enable it when an empty field is a valid choice, such as an optional filter that shows all dates when cleared. The button is hidden while the field is empty.
• Date limits (minDate, maxDate, isDateDisabled) — disabled dates can't be selected in the calendar, and presets whose period falls outside the limits are disabled.
• Opening — the popover opens on click, on focus, or on Down Arrow, Enter, or Space. Escape or an outside click closes it without changing the value.
• Close on selection — date and date range types apply the selection and close as soon as the user picks a day, the end of a range, or a preset.
• Close on save — time types (withTime) hold the selection until the user saves it, so the date, time, and time zone update the field together.
• Range length (minRange, maxRange) — for date ranges, days that would make the range too short or too long are disabled once the start date is chosen. For time ranges, an error explains the limit and saving is unavailable until the range fits.
• Time zones — time types include a time zone selector that defaults to the user's local time zone. Changing the time zone keeps the chosen time on the clock and moves the moment it represents.
• Unix timestamp — a single date and time can also be entered as a Unix timestamp.

Content

• Write labels as nouns or noun phrases that describe what the date represents, such as "Send date". Never label the field with the data type alone, such as "Date".
• Write placeholders as short phrases such as "Choose a date" or "Select a range". On an optional field, describe what an empty field means instead, such as "Full history".
• Never use a format hint such as "MM/DD/YYYY" as a placeholder — the field can't be typed into.
• Write description text as short, complete sentences explaining how the date is used or what limits apply to it.
• Write errors as direct instructions that name the dates the user can choose, such as "Choose a date after today." Never write vague errors such as "Invalid date", and never use "please".
• Name presets relative to today. Keep preset labels parallel in phrasing and units, such as "Last 7 days", "Last 30 days", "Last 90 days".
• Order presets from the shortest period to the longest.

Implementation Notes

• value and onChange take @internationalized/date objects, not strings or Dates: CalendarDate for a date, { start, end } of CalendarDate for a range, ZonedDateTime with withTime, and { start, end } of ZonedDateTime with both isRange and withTime. onChange receives null when nothing is selected. The exported DatePickerValue type covers all four shapes.
• The field is controlled — pair value with onChange to update the selection.
• isClearable requires onClear, and onClear must reset value itself — the clear button does not call onChange.
• withPresets only applies when isRange is set.
• presets replaces the default presets with an array of preset objects. A type: 'relative' preset takes label and timeAgo: { value, unit }; a type: 'custom' preset takes label and a callback returning { start, end }. Both accept an optional icon, tooltip, and onClick. A preset with onClick runs the callback instead of selecting its range, and date limits do not disable it.
• Default presets differ by type: date ranges use Last 24 hours, Last 7 days, Last 30 days, Last 12 weeks, and Last 365 days; date and time ranges use Last hour, Last 24 hours, Last 7 days, and Last 30 days.
• isPresetDisabled overrides the automatic preset disabling. Pass a boolean for all presets or a function receiving the preset and its calculated range.
• minDate and maxDate take CalendarDate. isDateDisabled takes precedence over both when provided.
• minRange and maxRange accept a number of days, a string like "2 weeks" or "6 months", or a DateTimeDuration. With withTime, string units can also be hours, minutes, or seconds.
• localTimeZone sets the time zone used to calculate "today" and the time zone selector's default. Omit it to use the user's local time zone.
• placeholder defaults to "Choose a date…" when empty.
• label, description, and error accept rich content in place of a plain string: React takes a ReactNode; Ember takes the :label, :description, and :error named blocks. Use this for labels with an optional indicator and for descriptions or errors with inline links.
• The DatePicker owns the leading calendar icon and the trailing clear button, so TextField's icon, elementBefore, and elementAfter are not accepted.
• defaultIsOpen renders the popover open initially. shouldAutoFocusCalendar (default true) moves focus into the calendar when it opens.
• popoverMiddlewareOptions, popoverAnimationTransitionDuration, and unsafe_popoverStyle configure the floating popover, not the trigger. Use unsafe_popoverStyle only as a last resort.
• Ember invocation is <PlumaDatePicker> with @argName args matching the React prop names. The Ember signature type is PlumaDatePickerSignature.