Design a date picker

Requirements: what to ask before drawing a calendar

A date picker is a control for entering a calendar date. It usually has two parts: a date field where you can type, and a calendar that opens in a popup so you can pick a day with the mouse, a finger, or the keyboard. Most products need one, and date bugs are common. They are rarely in the drawing; they are in what a date means.

The browser has a built-in control, input type="date". Design systems still build their own because the native popup can't be styled, can't pick a range, can't mark individual days as sold out, and looks different in every browser. Part of a strong answer is knowing when the native one is the better choice anyway, and we will come back to that in the mobile section.

Start with questions. Each answer below changes the design. The middle column is what this guide assumes.

Functional requirements

• Pick a single date, or a start and end date, from a month calendar that pages by month and by year.
• Type a date in the field in the user's own format, with clear messages for dates that don't exist or are out of range.
• Respect min, max, and a callback that marks single days unavailable.
• Show today, the selected date or range, and a preview of the range while hovering or moving focus.
• Work fully with a keyboard and a screen reader, following the WAI-ARIA date picker pattern.
• Submit in a normal form, and work as a controlled component in React.

Non-functional requirements

• Correct in every time zone: a date picked in Tokyo is the same date when a colleague in Los Angeles opens it.
• Fast: opening the calendar under 50 ms on a mid-range phone, and moving focus with arrow keys well under one frame (16 ms).
• Small: the picker and its date code should add under about 15 KB gzipped to a page, because it sits on sign-up and checkout pages where every kilobyte delays the first interaction.
• Localized: names, order, first day of the week, numbering, and right-to-left layout come from the locale, not from hand-written tables.
• Accessible: meets WCAG 2.2 AA, including visible focus and targets of at least 24 by 24 CSS pixels.

Out of scope, and why

• A full scheduling calendar with events in a week view: that's a different problem (calendar week view).
• Recurring dates like "every second Tuesday": that's a rules editor, not a picker.
• Time zone pickers: we take the zone as an input when a time is involved, we don't build the list of zones.

What makes a date picker hard

Drawing a month is a weekend project. Shipping a date picker that works for a design system used by many teams is not. Five things drive every decision in the rest of this guide.

1. A date is not a moment. "March 14" is a box on a wall calendar. It covers different hours in Tokyo and in Los Angeles. JavaScript's Date object is a single moment in time, counted in milliseconds since 1970 in UTC. Using one to hold the other is the source of the most common date bug on the web: the date that moves by one day.
2. Every locale writes and reads dates differently. 3/4/2026 is March 4 in the United States and April 3 in the United Kingdom. Weeks start on Sunday, Monday, or Saturday. Month names, digits, and the direction of the page all change.
3. It's a two-dimensional keyboard widget. A month is a grid of 7 columns and up to 6 rows. Arrow keys move by a day or a week, other keys jump by month or year, and screen reader users need to hear "Saturday, March 14, 2026", not "14".
4. It lives in a popup. The calendar floats over the page, must stay on screen near edges, takes focus when it opens, and gives focus back when it closes. That's the whole dropdown problem again, with a bigger popup.
5. Rules make some dates invalid, and the rules interact. A min, a max, sold-out nights from the server, a minimum stay of 2 nights, a range that may not cross a sold-out night. Each one is easy alone; together they decide what each click means.

The first point matters most, so look at it closely. When a user in Tokyo picks Saturday, March 14, 2026, they mean the whole day.

If the code turns that into a Date at local midnight, it becomes the moment 2026-03-13T15:00:00Z, because Tokyo is 9 hours ahead of UTC. A colleague in Los Angeles who loads the same moment sees Friday, March 13 at 8 in the morning. Nobody changed the date. The type did.

Keep that picture in mind. A calendar date is a label for a whole day, the same everywhere. A moment is a point on one shared timeline, which lands on different calendar days in different places.

Birthdays, due dates, check-in dates, and holidays are labels. Meeting start times, deadlines at 17:00 in Berlin, and log timestamps are moments. A good picker knows which one it's holding.

The value model: store a plain date, not a Date

The first decision is the type of the value: what the component holds, emits in onChange, and puts in the form. Everything else reads from it, so a wrong choice here leaks into every team that uses the picker.

The naive approach is a JavaScript Date, because it's built in and every library accepts one. Here is how it breaks in practice.

A user in Tokyo picks March 14. The picker creates new Date(2026, 2, 14) (months start at 0, which is its own trap), which is local midnight: the moment 2026-03-13T15:00:00.000Z. The form sends toISOString() to the server. The server stores the moment.

The user's manager in San Francisco opens the record, and her browser renders the moment in her zone: Friday, March 13. The bug report says "dates are off by one", and it only happens for some people, which makes it slow to find.

The reverse bug is just as common: a server sends the string 2026-03-14 and the client does new Date("2026-03-14"). The JavaScript spec says a date-only ISO string is parsed as UTC midnight, while a date-time string without an offset, like 2026-03-14T00:00, is parsed as local time. So in any zone west of UTC, such as all of the Americas, calling getDate() on the result gives 13. Two strings that look almost the same are parsed in two different zones.

// In a browser set to America/Los_Angeles (UTC-7 on this day):
new Date("2026-03-14").getDate();        // 13: date-only is parsed as UTC
new Date("2026-03-14T00:00").getDate();  // 14: date-time without offset is local
new Date(2026, 2, 14).getDate();         // 14: month index 2 means March

// A plain date never asks which zone it's in:
const value = "2026-03-14";              // what the picker stores and emits
Temporal.PlainDate.from(value).dayOfWeek; // 6 (Saturday), no zone involved

Temporal today

Temporal is the new date and time API in JavaScript, designed to replace Date. It has separate types for separate ideas: PlainDate for a day, PlainTime for a wall-clock time, ZonedDateTime for a moment in a named zone, and Instant for a raw moment. As of late 2026, Firefox ships it (since version 139) and Chrome and Edge ship it (since version 144), but Safari's stable releases don't yet.

So a picker that relies on it still needs a polyfill for Safari users, and a polyfill adds roughly 20 to 50 KB gzipped, depending on which one. Check the current state on MDN before you decide; it's moving.

That's why we keep Temporal behind a small internal adapter. The adapter exposes the handful of operations the picker needs: parse an ISO string, add days, months, or years, compare two dates, get the weekday, and get the number of days in a month. Today it can be about 60 lines of code built on Date.UTC, which is safe for pure day math because UTC never has a daylight saving change. When Safari ships Temporal, we swap the inside of the adapter and no team notices.

type PlainDate = { year: number; month: number; day: number }; // month is 1 to 12

const toUtc = (d: PlainDate) => Date.UTC(d.year, d.month - 1, d.day);
const fromUtc = (ms: number): PlainDate => {
  const x = new Date(ms);
  return { year: x.getUTCFullYear(), month: x.getUTCMonth() + 1, day: x.getUTCDate() };
};

export const addDays = (d: PlainDate, n: number) => fromUtc(toUtc(d) + n * 86_400_000);
export const compare = (a: PlainDate, b: PlainDate) => Math.sign(toUtc(a) - toUtc(b));
export const dayOfWeek = (d: PlainDate) => new Date(toUtc(d)).getUTCDay() || 7; // 1 Mon .. 7 Sun
export const daysInMonth = (year: number, month: number) => new Date(Date.UTC(year, month, 0)).getUTCDate();

export function parseIso(s: string): PlainDate | null {
  const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(s);
  if (!m) return null;
  const d = { year: +m[1], month: +m[2], day: +m[3] };
  return d.month >= 1 && d.month <= 12 && d.day >= 1 && d.day <= daysInMonth(d.year, d.month) ? d : null;
}

When a time is included: zones and daylight saving

Some uses need a time too: "remind me on March 8 at 2:30", or "the event starts November 1 at 1:30 in New York". The moment a time joins the date, the value needs a time zone, and the picker inherits a problem that the date-only version never had: daylight saving time (DST), when clocks jump forward or back by an hour.

In New York in 2026, on Sunday, March 8, clocks jump from 2:00 straight to 3:00. Any time from 2:00 to 2:59 that day doesn't exist. On Sunday, November 1, clocks fall back from 2:00 to 1:00, so every time from 1:00 to 1:59 happens twice, once in daylight time (UTC-4) and once in standard time (UTC-5). Governments also change these rules from time to time, so they are data, not constants.

Europe changes on different dates (the last Sunday of March and of October), and many countries don't change at all.

The naive approach builds a Date with new Date(2026, 2, 8, 2, 30). A browser in New York silently picks 3:30 instead, and the user never learns their reminder moved. A related trap: code that sets a picked date to "midnight" can land on 1:00 in zones that change clocks at midnight, as Brazil did until it dropped daylight saving time in 2019. Day math done in local time, like adding 24 hours to get "tomorrow", is wrong twice a year in every DST zone, because those days are 23 and 25 hours long.

Times that don't exist, and times that happen twice

Temporal names the choice disambiguation. When turning a wall time into a moment, you pass compatible, earlier, later, or reject. The default, compatible, moves a missing time forward by the length of the gap (2:30 becomes 3:30) and picks the earlier of two repeated times, which matches what Date has always done.

A picker should not hide this. Our design: validate on blur, and if the time falls in a gap, show a message such as "2:30 doesn't exist on March 8 in New York because clocks move forward. Did you mean 3:30?"

If it falls in an overlap, show a small choice with both offsets: "1:30 EDT (first)" or "1:30 EST (second)". That's two extra states, rarely seen, and they turn a silent data bug into a clear question.

const wall = Temporal.PlainDateTime.from("2026-11-01T01:30");
const zone = "America/New_York";

const first = wall.toZonedDateTime(zone, { disambiguation: "earlier" }); // offset -04:00
const second = wall.toZonedDateTime(zone, { disambiguation: "later" });  // offset -05:00
const repeated = first.offset !== second.offset; // true: ask the user which one

// A missing time (March 8, 2:30) gives a gap instead of a repeat:
const gapWall = Temporal.PlainDateTime.from("2026-03-08T02:30");
gapWall.toZonedDateTime(zone, { disambiguation: "reject" }); // throws a RangeError
gapWall.toZonedDateTime(zone).toPlainDateTime().toString();  // "2026-03-08T03:30:00"

The component API: modes, rules, and forms

A design-system picker has many callers with different needs: a date of birth on a sign-up form, a due date in a task panel, check-in and check-out on a booking page. The API has to make the common case one line and the hard cases possible, without twenty boolean props. Read the component API lesson (component-api-design) for the general rules; here we apply them.

type IsoDate = string; // "YYYY-MM-DD"
type DateRange = { start: IsoDate; end: IsoDate };
type CommonProps = {
  min?: IsoDate;
  max?: IsoDate;
  isDateUnavailable?: (date: IsoDate) => boolean; // must be fast and pure
  locale?: string;                               // defaults to the app's locale
  timeZone?: string;                             // IANA zone that owns "today", like a hotel's town
  firstDayOfWeek?: 1 | 2 | 3 | 4 | 5 | 6 | 7;      // override; defaults from locale
  name?: string;                                 // form field name
  required?: boolean;
  disabled?: boolean;
  label: string;                                 // visible label, required
  description?: string;                          // help text, like "Day, month, year"
  onVisibleMonthChange?: (month: string) => void; // "2026-03": fetch availability
  isLoading?: boolean;                           // availability for the visible months is loading
};
type DatePickerProps = CommonProps & {
  value?: IsoDate | null;            // controlled
  defaultValue?: IsoDate | null;     // uncontrolled
  onChange?: (value: IsoDate | null) => void;
};
type DateRangePickerProps = CommonProps & {
  value?: DateRange | null;
  defaultValue?: DateRange | null;
  onChange?: (value: DateRange | null) => void; // only complete ranges
  onStartChange?: (start: IsoDate) => void;      // first pick, for example to fetch prices
  minNights?: number;
  maxNights?: number;
  allowsUnavailableInside?: boolean;  // default false
};

Controlled, uncontrolled, and partial ranges

The picker supports both modes React developers expect. Controlled: the parent passes value and onChange and owns the state, which is what form libraries need. Uncontrolled: the parent passes defaultValue (or nothing) and the picker keeps its own state, which is enough for a simple filter. Switching between the two during the component's life is a bug, and the picker warns about it in development, the same way a native React input does.

Ranges add a question: what happens between the first click and the second? The user has picked a start but no end yet. If onChange fires with { start, end: null }, every caller must handle a half-finished range, and a controlled parent that validates "end must be after start" will reject it and wipe the click.

So the half-finished range is the picker's own internal state, and onChange fires once, with a complete range. A parent that really wants to react to the first click (for example, to fetch prices for the possible end dates) gets a separate onStartChange event, not a broken value.

min, max, and isDateUnavailable

min and max are ISO strings, compared as plain dates. isDateUnavailable is a function the picker calls for every visible cell, so 42 calls per month on each render, 84 with two months. It must be pure and fast: a Set lookup, not a network call.

The booking page fetches sold-out nights per month (more on that in the architecture chapter), puts them in a Set, and passes (d) => soldOut.has(d). A function beats a list because some rules are patterns, like "no weekends" or "only Tuesdays", and a list of every weekend for ten years would be silly.

Working inside a plain form

Many forms are posted without JavaScript state, or read with new FormData(form). If the picker has a name, it renders an input type="hidden" with that name and the ISO value. A range with name="stay" renders two: stay.start and stay.end, or names the caller chooses.

The visible field shows the localized text ("14/03/2026") while the form carries the machine value ("2026-03-14"): the server never parses a localized date. For required, the picker reports validity with setCustomValidity on its own focusable field so the browser's built-in validation and form.reportValidity() work as usual. Read the form state lesson (form-state) for how this fits into larger forms.

The input: typing a date in any locale

Clicking through a calendar is slow for dates far away. Picking a date of birth in 1987 from a month grid means dozens of clicks or a year dropdown. Typing 14/03/1987 takes two seconds.

So the field is not decoration around the calendar: for many users it's the main way in, and for keyboard and screen reader users it's often the easiest one. The GOV.UK Design System goes further and recommends plain typed fields, not a calendar, for dates people already know, like a date of birth.

Typing has three problems: the order of the parts (is 03/04/2026 March 4 or April 3?), the separators (slashes in the US and UK, dots in Germany as in 14.03.2026, hyphens elsewhere), and validity (31/02/2026 looks like a date and isn't one). A field that guesses wrong is worse than no field, because the wrong date looks fine until the hotel booking is for April.

Getting the order from the locale

Don't keep a table of formats by hand. Intl.DateTimeFormat already knows them, and formatToParts tells you the order and the separators for any locale. Format a known date, read the order of the day, month, and year parts, and you have both the parser's order and the hint text. For en-US that's month, day, year; for en-GB, de-DE, and fr-FR it's day, month, year; for ja-JP and ko-KR it's year, month, day.

function fieldOrder(locale: string) {
  const parts = new Intl.DateTimeFormat(locale, { day: "2-digit", month: "2-digit", year: "numeric" })
    .formatToParts(new Date(Date.UTC(2026, 2, 14)));
  return parts.filter((p) => p.type === "day" || p.type === "month" || p.type === "year").map((p) => p.type);
}
fieldOrder("en-US"); // ["month", "day", "year"]
fieldOrder("de-DE"); // ["day", "month", "year"]

function parseTyped(text: string, order: string[]): string | null {
  const iso = /^\d{4}-\d{2}-\d{2}$/.test(text.trim()) ? text.trim() : null; // pasted ISO
  if (iso) return parseIso(iso) ? iso : null;
  const nums = text.match(/\d+/g);
  if (!nums || nums.length !== 3) return null;           // "3/4" is rejected, not guessed
  const get = (t: string) => Number(nums[order.indexOf(t)]);
  const [y, m, d] = [get("year"), get("month"), get("day")];
  if (y < 1000) return null;                             // ask for four-digit years
  const out = `${y}-${String(m).padStart(2, "0")}-${String(d).padStart(2, "0")}`;
  return parseIso(out) ? out : null;                     // rejects 31/02 and month 13
}

Validation messages that help

Validate on blur and on submit, not on every keystroke: while someone types 1, 14, 14/0, the field is incomplete, not wrong. Each failure gets its own message, written in the user's language and naming the fix: "Enter a real date, like 14/03/2026" for text that can't be read, "February 2026 has only 28 days" for 31/02/2026, "Choose a date on or after 1 March 2026" for a date before min, and "14 March is sold out" for an unavailable date.

The message is linked to the field with aria-describedby and the field gets aria-invalid="true", so a screen reader reads it when focus returns. The input validation lesson (input-validation) covers the timing rules in depth.

Two more details. On phones, inputmode="numeric" brings up a number pad, but iOS's number pad has no slash key, so the parser also accepts eight digits with no separators, like 14032026. And the text box keeps whatever the user typed until blur; reformatting while they type moves the caret and feels like the field is fighting them.

The calendar grid: weeks, locales, and names

The calendar shows one month (or two, for ranges) as a table: a header with the month and year, a row of weekday names, and rows of weeks. Building it is a small pure function from three inputs, the visible month, the first day of the week, and the rules, to a list of cells. Getting it right means handling how many rows a month needs, which day starts the week, and what everything is called in the user's language.

Months need between 4 and 6 rows. February 2026 starts on a Sunday and has 28 days, so in the United States, where weeks start on Sunday, it fits in exactly 4 rows. In the UK, where weeks start on Monday, the same month needs 5, because February 1 sits alone in the last column of the first row.

August 2026 starts on a Saturday and has 31 days, so it needs 6 rows in both. If the grid grows and shrinks, the popup changes height as you page through months, the buttons under it jump, and a popup placed above the field moves away from it.

type Cell = { date: IsoDate; inMonth: boolean; disabled: boolean; isToday: boolean };

function monthGrid(year: number, month: number, firstDay: number, rules: Rules, today: IsoDate): Cell[] {
  const first: PlainDate = { year, month, day: 1 };
  const lead = (dayOfWeek(first) - firstDay + 7) % 7;   // empty slots before the 1st
  const start = addDays(first, -lead);
  return Array.from({ length: 42 }, (_, i) => {
    const d = addDays(start, i);
    const date = toIso(d);
    return {
      date,
      inMonth: d.month === month,
      disabled: rules.isOutOfRange(date) || rules.isUnavailable(date),
      isToday: date === today,
    };
  });
}

Which day starts the week

Sunday in the United States, Canada, and Japan; Monday in most of Europe; Saturday in Egypt and several other countries in the Middle East. The browser can tell you: new Intl.Locale("en-GB").getWeekInfo() returns an object whose firstDay is 1 (Monday, using 1 for Monday through 7 for Sunday), plus weekend days and minimalDays.

Support is the catch. Chrome (from version 130) and Safari (from version 17) have the method, older versions of both exposed a weekInfo property instead, and Firefox only added the method in version 153, long after the others. So the picker feature-detects the method, then the property, then falls back to a small table keyed by region, with Monday as the default. Teams can also pass firstDayOfWeek directly, because some users set a personal preference that differs from their region.

Note that the first day depends on the region, not the language. en-US starts on Sunday, en-GB on Monday: same language, different week. A locale with no region, like plain en, needs a sensible default; Intl.Locale can add the likely region with maximize().

Month names, weekday names, digits, and week numbers

• Header: new Intl.DateTimeFormat(locale, { month: "long", year: "numeric" }) gives "March 2026", "mars 2026", or "2026年3月". Don't glue a translated month name to a number yourself: word order and grammar differ.
• Weekday row: use weekday: "short" for the visible label, because narrow gives "S M T W T F S" in English, with two S and two T. Give each column header the full name ("Saturday") for screen readers.
• Digits: format day numbers with Intl, not String(day). Some locales, like Arabic in Egypt, use Arabic-Indic digits by default.
• Week numbers: optional, off by default, on for many European business apps. Intl doesn't compute them. ISO 8601 weeks start on Monday and week 1 is the week with the year's first Thursday; the US convention differs. minimalDays from week info tells you which rule a region uses.
• Other calendars: some locales default to a non-Gregorian calendar in Intl. Thai formatting, for example, shows the Buddhist year 2569 for 2026. Our grid is Gregorian, so we format with calendar: "gregory" to keep the header and the grid consistent, and list full support for other calendars as a known gap (React Aria shows it can be done with a calendar-aware date library).

Keyboard and screen readers

A calendar is a two-dimensional widget, so it can't be navigated with Tab alone: 42 tab stops per month would be unusable. The WAI-ARIA Authoring Practices Guide (APG) has a date picker dialog example that sets the expected model. Screen reader users who have used one accessible calendar expect the next one to work the same way, so we follow it instead of inventing keys. The lessons on ARIA patterns (aria-patterns) and keyboard navigation (keyboard-navigation) cover the general rules; this chapter is the calendar's version.

One tab stop: roving tabindex

The grid is one tab stop because exactly one day button has tabindex="0" and every other day has tabindex="-1". Arrow keys move that 0 to the new day and call .focus() on it. This is a roving tabindex, the same technique as tabs and toolbars (the tabs guide uses it too). When focus enters the grid, it lands on the selected date, or today if nothing is selected, or the first available day of the month if today isn't in view.

The alternative, aria-activedescendant, keeps real focus on the grid and points at a cell by id. It works, but some screen readers handle it less reliably inside tables, and the focused cell would not scroll into view by itself. Real focus on a real button is simpler.

What a screen reader should hear

• The popup is a dialog labeled by its purpose: "Choose check-in date". The month heading has an id, and the grid has role="grid" and aria-labelledby pointing at it, so entering the grid announces "March 2026, grid".
• Each day's accessible name is the full date, built with Intl.DateTimeFormat and dateStyle: "full": "Saturday, March 14, 2026", not "14". The visible text stays "14"; the full name goes in aria-label.
• State goes in attributes, not words in the label where an attribute exists: aria-selected="true" on the selected day's gridcell (buttons don't support it, so each td cell holds the button), aria-current="date" on today, aria-disabled="true" on blocked days. Reasons a day is blocked ("sold out") go in the label or a description, because there's no attribute for why.
• When the month changes, the new month name is announced. The heading sits in a polite live region (aria-live="polite"), as in the APG example, so Page Down announces "April 2026" before the focused day.
• The field's description tells users there's a calendar and how to type: "Format: DD/MM/YYYY. Press the calendar button to pick a date."
• The calendar button's name includes the chosen date, as in the APG example: "Change date, Saturday, March 14, 2026". When focus returns to it after a pick, the user hears the result.

The popup: dialog, focus, and placement

The calendar opens from a button next to the field. Three questions decide how that popup behaves: what kind of thing it is for assistive technology, where focus goes when it opens and closes, and where it appears on screen. The dropdown select guide solves the same layering and placement problem for a list; the calendar reuses that engine, so this chapter focuses on what's different.

The APG has a second date picker example worth knowing: the date picker combobox. There, the text field itself has role="combobox", aria-haspopup="dialog", and aria-expanded, and Down Arrow or Alt+Down Arrow opens the calendar. We keep the dialog example's simpler model, a plain text field plus a separate calendar button, because it needs fewer ARIA roles to get right. The field can still open the calendar on Alt+Down Arrow as a shortcut.

Focus on open, and back on close

Focus moves into the grid when the calendar opens, onto the selected date (or today, or the first available day). It doesn't go to the "previous month" button, even though that's first in the tab order, because the grid is what the user came for.

When the calendar closes by Escape, by a click outside, or by picking a date, focus goes back to the calendar button, so a keyboard user continues from where they were. The focus management lesson (focus-management) explains why losing focus to the body is one of the worst things a popup can do.

One case needs care: if the user clicks outside on another input, focus should stay on what they clicked, not jump back to the calendar button. So "return focus" only happens when focus would otherwise be lost, meaning it's on the body or inside the closing popover. The Popover API's light dismiss closes the popover on that outside click; our toggle event handler checks where focus is before restoring it.

Placement: below, flip above, stay on screen

The calendar is about 300 pixels wide and 340 tall, bigger than most dropdown lists, so it hits screen edges more often. Default placement is below the field, aligned to its start edge (left in left-to-right, right in right-to-left). If there's not enough room below, it flips above; if it would overflow sideways, it shifts in. Because the grid always has 6 rows, its height is stable, so a flipped popup stays attached to the field when you page months.

.date-field { anchor-name: --date-field; }

.calendar-popover {
  position-anchor: --date-field;
  position-area: block-end span-inline-end; /* below, starting at the field's start edge */
  position-try-fallbacks: flip-block, flip-inline;
  inset: auto;   /* undo the popover's default centering */
  margin: 4px 0;
}

/* Without anchor positioning, a script measures the field and sets top and left inline. */
@supports not (anchor-name: --a) {
  .calendar-popover { margin: 0; }
}

The Popover API is supported in all major browsers since 2024 (Baseline), so we use it everywhere for the top layer and light dismiss. CSS anchor positioning is newer: it only reached every major engine in 2026, so we feature-detect it with @supports and fall back to a small script positioner (Floating UI or our own) for older browsers. The script listens to scroll and resize on every scrolling ancestor and recomputes, which is exactly the work anchor positioning removes.

Range selection: two clicks and many rules

A range is picked with two actions: the first sets the start, the second sets the end. Between them, the picker is in a half-finished state that the single picker never has. That state is where every range rule lives, so we model it explicitly as a small state machine instead of a pile of booleans like isSelectingEnd and hasStart.

The machine has three states. Idle: a complete range (or nothing) is shown. Start picked: the user has chosen a start, and every move of the pointer or the keyboard focus updates a preview end. Check rules: the second choice is checked against the rules and, if valid, onChange fires with the complete range and the machine returns to idle.

Escape in the start-picked state drops the half range and goes back to the last committed value (a second Escape closes the popup), so a user can't lose a good range by starting a new one by accident.

The preview, for mouse and keyboard

While the start is picked, the days between the start and the hovered day are tinted, so the user sees the range before committing it. The preview follows keyboard focus too, not only the mouse: a keyboard user moving with arrows sees and hears the same thing. Each day's accessible name adds the preview result when it matters, like "Thursday, March 12, 2026, check-out, 2 nights", and after the second choice a polite live region announces "March 10 to March 14, 4 nights".

Rules that shape a range

• Minimum and maximum length. With minNights={2} and a start of March 10, March 11 is disabled as an end, announced as "Minimum stay is 2 nights". With maxNights={28}, days past April 7 are disabled.
• Unavailable days inside the range. By default a range can't contain a blocked day. Once the start is picked, the first blocked day after it caps the range, and every later day is disabled as an end. Some products allow it (a vacation-days request across a public holiday), so allowsUnavailableInside turns the cap off.
• Nights, not days. For stays, a range from March 10 to March 14 uses the nights of the 10th to the 13th. The 14th only needs to be free as a check-out day. That's a booking rule the page passes in through isDateUnavailable and a separate check-out rule; the picker's job is to ask per day and display the answer.
• Two months side by side. On wide screens, ranges show two months, so a stay crossing a month end is visible at once. Paging moves both by one month. On narrow screens it's one month at a time, or a vertical scroll of months in the full-screen sheet.
• Today. The first selectable day is "today" in the time zone that owns the dates (a hotel's town, for example), passed as a prop, not today on the user's laptop.

function canEndAt(start: IsoDate, end: IsoDate, r: RangeRules): string | null {
  const n = nightsBetween(start, end);
  if (n < 1) return "Pick a day after check-in";
  if (r.minNights && n < r.minNights) return `Minimum stay is ${r.minNights} nights`;
  if (r.maxNights && n > r.maxNights) return `Maximum stay is ${r.maxNights} nights`;
  if (!r.allowsUnavailableInside) {
    for (let d = start; d < end; d = addDaysIso(d, 1)) {
      if (r.isNightUnavailable(d)) return "Includes an unavailable night";
    }
  }
  return null; // valid end
}

The loop looks slow, but it's bounded by maxNights and runs only while a start is picked. For 84 visible cells and a 28-night maximum, that's at most a few thousand Set lookups, well under a millisecond. Even so, the grid computes it once per start (one pass that finds the first blocked night) rather than once per cell, as the performance section shows. Comparing ISO strings with < works because YYYY-MM-DD sorts as text in date order.

Architecture and data flow

With the decisions made, here are the parts and the lines between them. The main idea: pure logic (date math, the grid model, the range rules) sits in plain functions with no React and no DOM, state sits in hooks, and the visible components only render and forward events. That split is what lets the same core power the field, the popover picker, the inline booking calendar, and a team's custom markup.

Follow the data on a booking page. The page loads the listing with its time zone. The guest opens the calendar; the picker reports that March and April are visible. The page requests availability for those months and one month ahead, so paging feels instant, and caches each month for about a minute because sold-out nights change.

The response, a list of nights and their minimum stays, becomes a Set of blocked days and a lookup the picker calls per cell. When the guest commits a range, onChange gives the page { start: "2026-03-11", end: "2026-03-14" }; the page updates the URL and the price box, and the form posts the same two ISO strings. The server checks every rule again, because the client's view of availability can be a minute old.

The failure path matters too. If the availability request fails, the grid shows a short message inside the popover, "Couldn't load availability. Try again", with a retry button. The grid's aria-busy goes back to false and the live region reads the message, instead of a spinner that never ends.

Days stay selectable. The booking request is the real check, and blocking the whole calendar because a hint failed would stop people from booking at all.

The state, in one place

type PickerState = {
  value: IsoDate | null;              // committed value (or from props when controlled)
  draftText: string;                  // what's in the text box right now
  error: FieldError | null;           // "invalid" | "outOfRange" | "unavailable"
  isOpen: boolean;
  visibleMonth: string;               // "2026-03": first visible month
  focusedDate: IsoDate;               // owner of tabindex="0" in the grid
};

type RangeState =
  | { kind: "idle"; value: DateRange | null }
  | { kind: "startPicked"; start: IsoDate; preview: IsoDate | null; previous: DateRange | null };

Where each piece lives follows from who needs it. The committed value lives in the parent when controlled (often in a form library or the URL on a search page, as in the Airbnb guide). Draft text, the error, open state, visible month, focused date, and the range machine are UI state inside the picker: nobody outside needs them, and lifting them up would make every keystroke re-render the parent form. Availability lives in the page's server cache.

Phones, right-to-left, speed, size, and tests

The design works on a desktop in English. This chapter covers what changes on a phone, in Arabic or Hebrew, on a slow device, in the bundle, and in CI, where date bugs often hide.

Phones: the native picker or our own sheet

Right-to-left

In Arabic and Hebrew, the whole calendar mirrors: the first day of the week is on the right, the "next month" arrow points left and sits on the left, and the popover aligns to the field's right edge. Using logical CSS properties (margin-inline-start, inset-inline-end) and a grid that follows dir gets most of this for free.

The keyboard must mirror too: in right-to-left, Left arrow means the next day. Read the direction from the element with getComputedStyle(el).direction rather than the locale, so a Hebrew page with an English widget still behaves. The rtl-layouts lesson covers the layout side.

Performance: don't re-render 84 cells on every hover

The naive range calendar keeps hoveredDate in state at the top and passes it down, so every pointer move re-renders all 84 cells of a two-month view. On a mid-range phone that's a few milliseconds each time, and pointer moves can arrive about once per frame, so the preview stutters.

Three fixes, in order: memoize the grid model per month and first day with useMemo, so moving the pointer doesn't rebuild cells; wrap DayCell in React.memo and pass it small derived booleans (inPreview, isRangeEnd), so only cells whose state actually changes re-render, usually 2 to 10 per move; and compute range limits once per start (the first blocked night and the min and max end) instead of running the rule loop per cell.

Pointer events are handled once on the grid (event delegation), reading the day from a data-date attribute. Creating Intl.DateTimeFormat objects is far slower than calling format, so the 84 accessible labels reuse one cached formatter per locale.

Bundle size

This is why the adapter exists. The picker's job needs plain day math and Intl, both of which are tiny or free. Loading a large date library on a checkout page for that delays the page's first interaction for every user, while most of them never open the calendar. The calendar itself (grid, popover, range machine) is also loaded on demand: the field renders immediately, and the calendar code is fetched on first focus of the field or hover of the button, before the click lands.

Testing dates without flaky tests

• Freeze the clock. "Today" changes every day, so tests that render the current month break on the 1st or on December 31. Use fake timers with a fixed system time (vi.setSystemTime in Vitest, jest.setSystemTime in Jest) and pick risky days on purpose: January 31, February 29, 2028, and December 31.
• Run in several time zones. Set the TZ environment variable for Node test runs, for example TZ=America/Los_Angeles, TZ=Asia/Tokyo, and TZ=Pacific/Kiritimati (UTC+14), and run the date tests in each in CI. The off-by-one bug only shows up in zones on one side of UTC, so a team in one office never sees it.
• Browser tests with a zone and locale. Playwright's timezoneId and locale options run the real component in, say, ar-EG in Cairo and en-US in Los Angeles, catching first-day-of-week and right-to-left bugs.
• Unit tests on the pure parts. The adapter, monthGrid, the parser, and canEndAt are pure functions, so most cases are fast table tests: every month of a year for row counts, every locale order for parsing, DST dates for time handling.
• Accessibility checks. Automated rules (axe) catch missing labels; keyboard tests drive Page Down and Shift+Page Down across month ends; and a manual screen reader pass covers what tools can't hear.

Running it in the interview

A date picker question is a test of whether you've shipped one. Interviewers listen for the value model in the first minutes, a real keyboard model, and locale awareness. Drawing a pretty grid for 20 minutes is the most common way to run out of time with none of those said.

If the interviewer pushes on one area, follow them there and drop the later rows. Depth on the value model or the keyboard model is worth more than covering bundle size.

Follow-up questions and strong answers