Skip to content

Improve accessibility for month and year dropdowns (select + custom modes)#80

Open
balajis-qb wants to merge 2 commits into
mainfrom
issue-6223/fix/month-year-dropdown-accessibility
Open

Improve accessibility for month and year dropdowns (select + custom modes)#80
balajis-qb wants to merge 2 commits into
mainfrom
issue-6223/fix/month-year-dropdown-accessibility

Conversation

@balajis-qb

@balajis-qb balajis-qb commented Jun 10, 2026

Copy link
Copy Markdown
Collaborator

Description

This PR improves the accessibility of the month and year dropdowns in the date picker, covering both native select mode and custom dropdown (scroll) mode.

The changes ensure that both implementations provide correct semantics and a better experience for screen reader users, while keeping the existing API surface minimal.

Background

This PR addresses the issue raised in:

Issue: Hacker0x01#6223

An earlier attempt was made in:

Previous PR: Hacker0x01#6232

This PR replaces the earlier one with an updated implementation that incorporates prior review feedback.

Description

Linked issue: 6223

Problem
The current implementation of month and year dropdowns has few accessibility gaps:

  • Native select dropdowns lack contextual labels, leading to ambiguous screen reader output (e.g., “June, combo box” without indicating it represents a month)
  • Custom dropdown (scroll mode) does not fully follow listbox semantics
  • Incorrect role usage (e.g., role="button" for selectable items) leads to inconsistent screen reader behavior
  • Navigation controls (e.g., “Show earlier/later years”) rely on non-semantic elements and inconsistent labeling

These issues result in:

  • Reduced clarity for screen reader users
  • Inconsistent keyboard navigation
  • Non-standard ARIA patterns

Changes

  1. Native select mode
  • Added aria-label="Month" / aria-label="Year" to provide context (e.g., “Month, June, combo box”)
  • Avoided adding to prevent additional DOM complexity and ID management
  • Did not introduce new props for ARIA labels to keep API surface minimal
  1. Custom dropdown (scroll) mode
  • Listbox semantics
  • Ensured dropdown uses listbox pattern:
options → role="option"
selection → aria-selected
  • Removed incorrect role="button" usage for selectable items
  • Screen reader improvements
  • Added visually hidden (sr-only) text where needed (e.g., “Month”) for consistent announcements
  1. Year dropdown navigation (pagination)
  • Replaced anchor elements () with semantic elements
  • Added accessible names using visually hidden text (instead of relying solely on aria-label) for better NVDA support

Interaction behavior
Navigation controls remain buttons (actions), not options. They are:

  • reachable via Tab
  • not part of arrow key navigation (listbox behavior)

This aligns with ARIA practices, where only role="option" participates in arrow navigation.

API Impact

  • No new props introduced (e.g., ariaMonthDropdownLabel)
  • Avoided expanding API for internal accessibility labels
    If needed, support for custom aria-labels can be added in a future iteration.

Testing

Tested with:

  • NVDA
  • Windows Narrator

Contribution checklist

  • I have followed the contributing guidelines.
  • I have added sufficient test coverage for my changes.
  • I have formatted my code with Prettier and checked for linting issues with ESLint for code readability.

…sibility

- Changed month option buttons from <div> to <li> elements to better reflect their role in a list.
- Updated ARIA roles and attributes for better screen reader support, including setting role="option" and aria-haspopup="listbox".
- Added aria-hidden to the down arrow and check mark for improved accessibility.
- Enhanced test cases to verify ARIA attributes and accessibility features in the month dropdown.

Closes Hacker0x01#6223
…lity

- Updated year option buttons from <div> to <li> elements to better represent their role in a list.
- Changed ARIA roles and attributes for better screen reader support, including setting role="option" and aria-haspopup="listbox".
- Added aria-hidden to the down arrow and check mark for improved accessibility.
- Introduced a new <ul> wrapper for year options to enhance semantic structure.
- Enhanced test cases to verify ARIA attributes and accessibility features in the year dropdown.

Closes Hacker0x01#6223
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant