Date range picker

Problem Context

• The user is selecting a period for analytics, booking, scheduling, eligibility, reporting, campaign planning, or event duration.
• The relationship between dates matters: start, end, days included, duration, weekdays, cross-month spans, or blackout dates.
• Common ranges may be faster through presets but custom dates must remain possible.
• The interface may update expensive search results, charts, availability, or pricing after the range changes.
• The service must store unambiguous start and end dates and handle invalid or out-of-window values.

Selection Rules

• Choose date range picker when the answer is a continuous start-to-end period and users need to see the included days.
• Use a single date picker for one appointment, deadline, or booking date.
• Use date input when users already know both dates and calendar adjacency does not affect the answer.
• Use filter panel when the range is one draft criterion among multiple grouped filters that should be applied together.
• Use select or segmented choices for a small set of fixed periods such as Today, This month, or Fiscal Q3 when custom dates are not allowed.
• Keep start and end labels visible and editable instead of hiding both boundaries inside one compound value.
• Show the range band between endpoints so users can verify inclusivity.
• Use Apply and Cancel when selecting the range changes charts, tables, pricing, availability, or other expensive results.
• Validate end date after start date, minimum date, maximum date, blocked dates, and maximum duration before committing.
• Preserve one valid boundary when the other boundary is invalid.

Required States

• Empty start and end fields with visible labels, date-format hints, and a calendar trigger.
• Open calendar with start endpoint active and no end selected.
• Hover or keyboard preview state showing the possible in-range days before end selection.
• Complete selected range with start date, end date, and all included days visibly connected.
• Preset range selected state synchronized to both endpoint fields and the calendar band.
• Manual endpoint typed state that updates the same range model as calendar selection.
• Invalid order error when end date is before start date.
• Too-long duration error when the span exceeds the service limit.
• Out-of-window or disabled-date state for blocked dates.
• Dirty unapplied state with Apply and Cancel actions.
• Applied state showing canonical start and end dates.

Interaction Contract

• Opening the picker reveals both endpoint fields, presets when available, and a calendar that keeps the current range visible.
• The first calendar click sets or replaces the start date; the second valid click sets the end date and highlights the full range.
• Hovering or focusing a potential end date previews the included range without committing it.
• Typing in either endpoint field updates only that boundary and validates against the other boundary.
• Preset selection writes both endpoint fields and highlights the matching calendar range before Apply.
• Apply commits the complete valid range; Cancel restores the previously applied range.
• Submitting validates required endpoints, date format, real dates, start-before-end order, blocked dates, service bounds, and maximum span.
• Errors name the failing boundary and keep the other boundary visible for correction.

Implementation Checklist

• Define the range purpose, inclusive or exclusive end semantics, default range, preset ranges, min and max dates, disabled dates, maximum duration, display format, and canonical storage format.
• Build two labelled inputs, persistent hints, calendar trigger, preset list, calendar month heading, weekday headings, start state, end state, in-range state, preview state, and Apply and Cancel controls.
• Store range state as explicit start and end values rather than parsing a display string.
• Synchronize typed endpoints, preset choices, calendar clicks, hover previews, dirty state, and applied state.
• Validate date format, impossible dates, start after end, same-day ranges, minimum date, maximum date, disabled dates, and maximum span on client and server.
• Announce active endpoint, selected start, selected end, in-range dates, disabled reasons, month changes, and validation errors to assistive technology.
• Test keyboard selection of both endpoints, screen readers, zoom, forced colors, mobile layout, cross-month ranges, presets, cancel recovery, server-returned errors, and timezone boundaries.

Common Generated-UI Mistakes

• Using two unrelated single-date pickers that do not validate order or show included days.
• Collapsing the range into one unlabeled field with ambiguous dash-separated dates.
• Refreshing analytics results before the user applies a complete range.
• Hiding custom range entry behind presets only.
• Clearing the valid start date when the end date fails validation.
• Accepting an end date before the start date.
• Failing to show whether endpoints are inclusive.
• Using a range picker for approximate periods that users express in words.

Critique Questions

• Does the task require a continuous period, or is a single date enough?
• Are start and end labels visible and programmatically separate?
• Can users see every day included in the range before applying it?
• Which presets match real user decisions, and can users still enter custom dates?
• When should results update: on hover, on endpoint selection, or only after Apply?
• What happens when the end date is before the start date, blocked, or too far away?