Support independently controlled displayed months in multi-month range calendars

[Albatrosso]

Support independently controlled displayed months in multi-month range calendars

Summary

I would like to propose an API for independently controlling the visible months in a multi-month range calendar.

Today, numberOfMonths={2} renders a contiguous sequence of months derived from a single starting month. This works well for common date pickers, but it is limiting for range-selection UIs where the start and end dates may be far apart and each side of the picker represents a different endpoint.

Use case

In a data-heavy reporting/filtering UI, users often select date ranges spanning many months or years.

For example:

• Start date: January 2024
• End date: December 2025

When the range picker opens, the most useful layout is:

• left calendar: January 2024
• right calendar: December 2025

This lets users immediately see and adjust both endpoints of the selected range.

With the current numberOfMonths={2} model, the picker can show:

• January 2024
• February 2024

or, if anchored near the end:

• November 2025
• December 2025

but not both endpoint months at the same time unless they happen to be adjacent.

Current behavior

numberOfMonths={2} appears to model the visible calendars as:

[firstMonth, addMonths(firstMonth, 1)]

The recent fix for multi-month dropdown navigation is useful: selecting a month in the second calendar can keep that selected month in the second calendar by shifting the common start month.

However, the visible months are still contiguous. There does not seem to be a way to say:

visibleMonths={[startDateMonth, endDateMonth]}

or to control each displayed month independently.

Expected capability

It would be useful if DayPicker supported a controlled multi-month display where each visible month can be independently specified.

Conceptually:

<DayPicker
  mode="range"
  selected={range}
  onSelect={setRange}
  visibleMonths={[range.from, range.to]}
  onVisibleMonthsChange={setVisibleMonths}
/>

or another API shape along these lines:

<DayPicker
  mode="range"
  selected={range}
  onSelect={setRange}
  months={[
    { month: startPanelMonth, onMonthChange: setStartPanelMonth },
    { month: endPanelMonth, onMonthChange: setEndPanelMonth }
  ]}
/>

The exact API is less important than the capability: the visible months should not have to be adjacent.

Why this matters

This is useful for range filter UIs where:

• the range can span months or years
• both endpoints matter equally
• the picker is opened from an already-selected range
• users may need to adjust only the start or only the end date
• min/max or disabled date constraints still apply
• custom day rendering and range highlighting should continue to work

Without this, applications need to render two separate DayPicker instances and coordinate range state, hover preview, endpoint highlighting, disabled days, navigation bounds, and accessibility behavior manually.

Backward compatibility

This could be additive. Existing numberOfMonths behavior could remain unchanged.

The independent-month behavior could be enabled only when a new controlled prop is provided, such as visibleMonths, displayMonths, or a similar API.

Prior related issues

This is related to the multi-month dropdown behavior discussed in:

• Dropdown should change the month where it is displayed #2741
• fix: correct dropdown navigation in multi-month calendars #2977

That fix improves dropdown behavior for contiguous multi-month calendars. This proposal is about a separate capability: non-contiguous independently controlled displayed months.

Willingness to contribute

If this direction sounds aligned with DayPicker's goals, I would be interested in exploring an implementation and adding tests/examples.

[gpbl]

@Albatrosso cool, thanks for the idea!

I think the use case makes sense, e.g. for range pickers where the start and end months are far apart.

We should however explore this first, as a small draft PR focused on the core behavior before finalizing the API. The feature touches some assumptions in DayPicker: the rendered months are based on one anchor month + numberOfMonths, and those months are expected to be contiguous. Date generation, navigation, dropdowns, focus, and onMonthChange, etc. rely on that model.

I'd work on a prototype with a minima visibleMonths-style API, keep the existing month / defaultMonth / numberOfMonths behavior unchanged, and then iterate on naming and callbacks once we see how it works in practice.

Some ideas for the API:

• I’d avoid at first using the numberOfMonths here (e.g make this calendar view only displaying 2 months).
• I would avoid also touching onMonthChange because today it means “the single anchor month changed”. With visibleMonths, there is no single anchor month.

function RangePicker({ selected }) {
  const [visibleMonths, setVisibleMonths] = useState([
    startOfMonth(selected?.from ?? new Date()),
    startOfMonth(selected?.to ?? addMonths(new Date(), 1)),
  ]);

  return (
    <DayPicker
      mode="range"
      selected={selected}
      visibleMonths={visibleMonths}
      onVisibleMonthsChange={setVisibleMonths}
    />
  );
}

of onVisibleMonthsChange, the API could be something like

visibleMonths?: Date[];
defaultVisibleMonths?: Date[];
onVisibleMonthsChange?: (
  months: Date[],
  context: {
    changedIndex?: number;
    month?: Date;
    source?: "navigation" | "dropdown" | "keyboard";
  }
) => void;

What do you think?

[Albatrosso]

I'm back with PR #3002

[Albatrosso]

@gpbl Thanks for the feedback and the suggested API shape!

I agree with the approach extending the API with a separate set of props. Extending is better than changing here.

I'll prepare a draft PR focused on the core behavior and link it back to this discussion.

[Albatrosso]

@gpbl Hey! Just a gentle ping on #3002 would love your feedback when you get a chance

[gpbl]

Sorry for the delay, I’m a bit busy lately :(

I already checked it out, and it sounds like good progress! I think there may be some issues with the animation tho...

It would also be great to add an example to the repo’s example app, so we can test it directly in a browser.

Thanks for your patience here @Albatrosso !