Date Range Picker HTML CSS JS — Dual Calendar Popup

A date range picker is one of the most complex form components to build correctly. Unlike a single date picker, it must handle two selection points (start and end), a live hover preview showing the range in flight, dual month panels that stay synchronized, month navigation that respects both panels, keyboard accessibility, and click-outside-to-close — all in a single compact popup.

This snippet builds a complete, production-quality date range picker entirely in HTML, CSS, and vanilla JavaScript — no Flatpickr, no date-fns, no external calendar library.

State Machine Design

The picker has three selection states, tracked by two Date variables — start and end — and one hover variable:

1. No selection — both null. First click sets start, leaves end null. 2. Start selected, no end — first half of range. Hovering cells updates hovering, repainting the preview. Second click sets end. If end < start, the two are swapped. 3. Range complete — both set. Clicking a new cell resets to state 1 and starts a new range.

This three-state machine is the core of the component. Every calendar render reads start, end, and hovering to determine the class of each day cell: selected-start, selected-end, in-range, hover-preview, today, or plain.

Dual Month Panel Architecture

Two month panels render side by side. The left panel shows the month at cursorMonth and cursorYear. The right panel always shows the next month. Navigation arrows advance or retreat cursorMonth (adjusting cursorYear when crossing December or January) and re-render both panels.

Each panel is rendered by renderPanel(container, year, month). This function: computes the first day of the month (using new Date(year, month, 1).getDay() to get the starting weekday), fills empty cells before day 1 for alignment, generates day cells 1 through the month's last day, and appends them to the grid container.

Computing Month Start Day and Empty Cells

The calendar grid has 7 columns (Sun–Sat). new Date(year, month, 1).getDay() returns 0–6 for the weekday of the first of the month. If the first falls on Wednesday (day 3), three empty <div class="cal-cell empty"> elements are prepended before day 1 to shift it into the correct column. Days from the previous month are NOT shown — only blank placeholders — matching the common pattern used by Google Calendar, Airbnb, and most date pickers.

Live Hover Preview

While the user has selected a start date but not yet an end date, moving the mouse over any day cell fires a mouseover event. The handler sets hovering = new Date(year, month, day) and calls renderBothPanels() to repaint with the updated preview. Cells between start and hovering receive the hover-preview class (a lighter shade than the confirmed in-range class), giving users instant visual feedback before they click.

This re-render-on-hover approach is simpler than maintaining a separate preview layer and scales to any number of cells without DOM manipulation.

Range Cell Classification

For each day cell, the renderer checks three conditions: - Is this day === start? → class selected-start (rounded left cap) - Is this day === end? → class selected-end (rounded right cap) - Is this day between start and end (or between start and hovering)? → class in-range or hover-preview (flat fill)

Date comparison uses integer arithmetic: d.getTime() returns milliseconds since epoch. isSameDay(a, b) checks year, month, and date equality. isBefore(a, b) and isAfter(a, b) compare epoch values. This avoids any timezone ambiguity from direct Date subtraction.

Popup Open/Close and Click Outside

The popup is position: absolute below the trigger button. It opens with a CSS class toggle that sets opacity: 1, transform: translateY(0), and pointer-events: auto. Click-outside detection uses a mousedown event listener on document — if e.target.closest('.picker-wrap') is null (the click was outside the entire picker), the popup closes. The listener is added on open and removed on close to avoid stacking multiple listeners.

Keyboard Navigation

The trigger button has aria-haspopup="true" and the popup has role="dialog" aria-modal="true". When open, keydown on the document handles: Escape closes the popup. Arrow key navigation through day cells requires tabindex management — day cells get tabindex="0" and ArrowLeft/Right/Up/Down move focus between them. This matches WCAG date picker guidance.

Output Format

A getValue() function returns { start: Date, end: Date | null } for programmatic access. The display string uses toLocaleDateString('en-US', { month: 'short', day: 'numeric', year: 'numeric' }) to format both dates as "Jun 10, 2025 – Jun 20, 2025" in the trigger button label.