Skip to content

fix(a11y): keep keyboard-focused search suggestion visible (WCAG 2.4.11)#412

Open
WanjohiSammy wants to merge 3 commits into
masterfrom
swanjohi/search-typeahead-focus-scroll
Open

fix(a11y): keep keyboard-focused search suggestion visible (WCAG 2.4.11)#412
WanjohiSammy wants to merge 3 commits into
masterfrom
swanjohi/search-typeahead-focus-scroll

Conversation

@WanjohiSammy

@WanjohiSammy WanjohiSammy commented Jul 7, 2026

Copy link
Copy Markdown
Member

Problem

WCAG 2.4.11 Focus Not Obscured (Minimum). When a user types in the top-navbar search box and arrows through the autocomplete suggestions, the keyboard-focused suggestion could be scrolled off-screen (obscured), because the page does not reliably keep it in view. This is most visible on short or zoomed-in viewports where the suggestion list is taller than the visible area.

This completes the earlier partial fix in #406 (scroll active search suggestion into view), which did not fully resolve the issue across browsers and arrow directions.

Root cause

The navbar search input is driven by two keyboard navigators at once:

  1. Legacy Swiftype (jquery.swiftype.autocomplete.js) - owned the visible highlight (active class) and Enter selection.
  2. ARIA ComboboxAutocomplete (combobox-autocomplete.js) - owns aria-selected / aria-activedescendant and scroll-into-view.

Fix

Make the suggestion list scroll internally (the standard ARIA combobox pattern) and make the combobox the single keyboard navigator.

Before

image

After

image

@gathogojr

gathogojr commented Jul 10, 2026

Copy link
Copy Markdown
Contributor

This PR directly modifies public/jquery.swiftype.autocomplete.js, which appears to be a vendored third-party library (the jQuery Swiftype autocomplete plugin) rather than code we own. Patching a vendored dependency in place makes it hard to pull upstream updates/security fixes later, since our changes will conflict or get silently overwritten/lost.

Could we instead:

  • Check if Swiftype/jQuery already exposes hooks/events for this behavior (e.g., a config option or extension point) instead of editing the library source, or
  • If a patch is truly required, isolate it (e.g., a small wrapper/monkey-patch applied after load, or a documented local fork with a clear header noting what was changed and why), so future upstream updates can be reconciled more easily.

Could you clarify whether this file is actually maintained upstream/via a package manager, or if it's already treated as a local, hand-maintained copy in this repo? That would determine whether this is a real risk or a non-issue.

WanjohiSammy and others added 3 commits July 10, 2026 18:35
The navbar search box was driven by two keyboard navigators at once (legacy
Swiftype and the ARIA ComboboxAutocomplete), and the suggestion list had no
height cap so the whole page scrolled to reveal lower options. Together these
let the keyboard-focused suggestion be obscured.

Cap the suggestion list to the viewport and scroll it internally (the standard
ARIA combobox pattern) so the page never scrolls and the input stays in view,
and make the combobox the single navigator that keeps the visible highlight in
sync with aria-selected. Enter still selects the highlighted suggestion.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@WanjohiSammy WanjohiSammy force-pushed the swanjohi/search-typeahead-focus-scroll branch from ec367d2 to ad6a8a8 Compare July 10, 2026 15:35
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.

2 participants