[Accessibility] NVDA announces all selected dates in random order when calendar mounts inside a popover

[armhaj]

Describe the bug
When using react-datepicker in date range mode with the inline prop inside a popover, NVDA screen reader announces all selected date cells in a non-sequential, unpredictable order as soon as the popover opens — even if focus lands elsewhere in the popover (e.g. a tabs widget).

The root cause is that NVDA enters browse mode when a dialog opens and sweeps the entire dialog with its virtual cursor. Because the calendar renders all selected date cells with aria-selected="true" on mount, NVDA reads them all out immediately. The library currently provides no focus management API (e.g. autoFocus targeting a day cell, or an onCalendarOpen callback with a stable DOM reference) to suppress or control this behavior.

To Reproduce

1. Open the CodeSandbox: https://codesandbox.io/p/sandbox/whmgvn
2. Enable NVDA
3. Open the popover
4. Listen to the NVDA announcement on open

Observed behavior
NVDA reads all selected dates immediately upon calendar mount, in random order:

Choose Friday, June 6th, 2025 selected row 2 Friday column 6
Choose Saturday, June 7th, 2025 selected row 2 Saturday column 7
Choose Monday, June 9th, 2025 selected row 3 Monday column 2
Choose Sunday, June 8th, 2025 selected Sunday column 1
Choose Tuesday, June 3rd, 2025 selected row 2 Friday column 3
...

Expected behavior
When the calendar mounts, no automatic announcements should be triggered. Selected state should be communicated only when the user individually focuses a date cell (e.g. "June 6th, 2025, selected").

Screen recording

bug_selected_random.mp4

CodeSandbox
https://codesandbox.io/p/sandbox/whmgvn

Desktop:

• OS: Windows 11
• Browser: Chrome (148.0.7778.217)
• Screen reader: NVDA (2026.1 (2026.1.0.55743))
  "react": "18.2.0",
  "react-dom": "18.2.0",
  "react-datepicker": "^9.1.0"

Additional context
A possible fix would be for the library to explicitly move focus to a specific day cell (e.g. the range start date or today) when the calendar mounts, following the ARIA authoring practices for date picker dialogs. This would prevent NVDA from sweeping the grid in browse mode.

[balajis-qb]

Thank you for reporting the issue, @armhaj

I analyzed the issue you shared. This appears to be expected screen reader behavior rather than a react-datepicker bug.

When a container is exposed as a modal (role="dialog" aria-modal="true"), screen readers like NVDA may present dialog content on initial mount if focus lands on the dialog itself or a non-primary control (e.g., a button). I verified the same behavior with MUI’s date picker, so this is not specific to this library.

The key difference with the WAI-ARIA date picker example (https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/examples/datepicker-dialog/) is focus management: it explicitly moves focus to the active date (gridcell) on open. That places the user directly inside the grid (the primary interaction surface), so only the focused date is announced.

In our case, we don’t move focus into the grid on open, which leads to the more verbose announcement.

I tested this locally by forcing focus to the active date:

useEffect(() => {
  if (isOpen && dialogRef.current) {
    setTimeout(() => {
      const activeDay = dialogRef.current.querySelector(
        '.react-datepicker__day--range-start, \
         [role="gridcell"][tabindex="0"]'
      ) as HTMLElement;

      activeDay?.focus();
    }, 0);
  }
}, [isOpen]);

With this, NVDA announces only the selected date, matching the ARIA example.

From a library perspective, we probably shouldn’t enforce auto-focus by default since it can conflict with existing consumer focus management (inline vs popup, controlled inputs, etc.).

A reasonable improvement would be to expose an imperative API (e.g., focusSelectedDay) so consumers can opt into this behavior when needed.

[armhaj]

Thank you for reporting the issue, @armhaj

I analyzed the issue you shared. This appears to be expected screen reader behavior rather than a react-datepicker bug.

When a container is exposed as a modal (role="dialog" aria-modal="true"), screen readers like NVDA may present dialog content on initial mount if focus lands on the dialog itself or a non-primary control (e.g., a button). I verified the same behavior with MUI’s date picker, so this is not specific to this library.

The key difference with the WAI-ARIA date picker example (https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/examples/datepicker-dialog/) is focus management: it explicitly moves focus to the active date (gridcell) on open. That places the user directly inside the grid (the primary interaction surface), so only the focused date is announced.

In our case, we don’t move focus into the grid on open, which leads to the more verbose announcement.

I tested this locally by forcing focus to the active date:

useEffect(() => {
  if (isOpen && dialogRef.current) {
    setTimeout(() => {
      const activeDay = dialogRef.current.querySelector(
        '.react-datepicker__day--range-start, \
         [role="gridcell"][tabindex="0"]'
      ) as HTMLElement;

      activeDay?.focus();
    }, 0);
  }
}, [isOpen]);

With this, NVDA announces only the selected date, matching the ARIA example.

From a library perspective, we probably shouldn’t enforce auto-focus by default since it can conflict with existing consumer focus management (inline vs popup, controlled inputs, etc.).

A reasonable improvement would be to expose an imperative API (e.g., focusSelectedDay) so consumers can opt into this behavior when needed.

@balajis-qb Thank you so much for figuring this out! You are right, I checked with other libraries and this happens there too. I'll leave it up to you if you want to close this bug report or keep working on exposing an imperative API for this specific use case.