Add reopenOnFocusWhenValid prop

[andygout]

Description

This PR adds changes to accept a new prop: reopenOnFocusWhenValid.

Current behaviour

Currently, the autocomplete's logic works on the following basis:

Input value does not match any of the options (though options are present)

1. Enter input
2. Blur input (e.g. click outside the autocomplete component)
3. Focus input
4. The menu of options re-displays

Screen.Recording.2026-01-10.at.15.00.47.mov

Reference: https://alphagov.github.io/accessible-autocomplete/examples/form.html

Input value does match an option

1. Enter input
2. Blur input (e.g. click outside the autocomplete component)
3. Focus input
4. The menu of options does not re-display

Screen.Recording.2026-01-10.at.15.01.57.mov

Reference: https://alphagov.github.io/accessible-autocomplete/examples/form.html

Requirement

This behaviour is appropriate when the autocomplete component is being used in the context of an HTML form in that the objective was simply to get the value into the field so that when the form is submitted the value will be in the body of the POST request.

This should be continue to be supported and is the reason that the fix for the issue this PR seeks to solve cannot simply be changing the this line:

• from: validChoiceMade: this.isQueryAnOption(newQuery, options)
• to: validChoiceMade: false

However, when using the autocomplete component to serve as a site search (i.e. not in the context of an HTML form) and, for example, where a custom onConfirm function sends the user to the URL of the selected option rather than putting the value of the selected option in the input field, in the case of the second above-described scenario, this behaviour becomes inhibiting.

For example, when the user re-focuses the input, they are unable to take any further action without editing the input value to re-generate options to re-open the menu so that they can then interact with the options (which serve as CTA links).

Even pressing the enter key will have no effect as it will only have an effect if the menu is open (which in this case it will not be):

accessible-autocomplete/src/autocomplete.js

Lines 367 to 375 in b2a1f12

	handleEnter (event) {
	if (this.state.menuOpen) {
	event.preventDefault()
	const hasSelectedOption = this.state.selected >= 0
	if (hasSelectedOption) {
	this.handleOptionClick(event, this.state.selected)
	}
	}
	}

Screen.Recording.2026-01-10.at.15.07.33.mov

---

Side note: edge case issue

Even in the context of an HTML form, the existing logic is arguably not entirely intuitive. Taking the alphagov (Government Digital Service) example of autocompleting country names:

"guin" is a partial match on the following countries, and so they all appear in the menu of options:

• Equatorial Guinea
• Guinea
• Guinea-Bissau
• Papua New Guinea

"guinea" is a total match on Guinea though still only a partial match on:

• Equatorial Guinea
• Guinea-Bissau
• Papua New Guinea

However, the behaviour has changed owing to an exact match on one of those results even though a user may still want to see those other ones when re-focusing on the input.

With larger data sets (in which there are more such overlaps), this issue is likely to be more pronounced.

Screen.Recording.2026-01-10.at.15.26.19.mov

However, as per the following section, even with this edge case, re-displaying the partial matches may still justifiably be considered distracting screen reader noise and ultimately the better trade-off.

---

Historical intent

The original commits of the code that is modified by this PR are included in this PR: alphagov/accessible-autocomplete#355

• Commit 10d797e

  • BEHAVIOUR : Refine component behaviour to silence the aria live region when the input element is out of focus, or when a valid input value is detected. Reduces distracting screen reader noise that might otherwise suggest to the user that further action is needed.

• Commit 89110b7

  • BEHAVIOUR : Refinement to ensure result list menu is redisplayed on input focus, where a matched query is present and no valid choice has yet been made. Alignment with the audio behvaiour in terms of the silenced / unsilenced aria live region, to ensure that when the live region announces result availability, the results are actively selectable.

The key point is in the first of those commit messages (marked in bold). Outside the context of an HTML form, further action will be required, i.e. the user has yet to select one of the options that serve as a CTA to send them to another page. Furthermore, in this context if the menu does not re-open then it is not even possible for any further action to be taken, which is likely to result in frustration.

---

In the scenario of using the autocomplete component for a site search, the following behaviour is desirable:

Input value does not match any of the options (though options are present)

1. Enter input
2. Blur input (e.g. click outside the autocomplete component)
3. Focus input
4. The menu of options re-displays

(i.e. the same as before)

Screen.Recording.2026-01-10.at.15.10.07.mov

Input value does match an option

1. Enter input
2. Blur input (e.g. click outside the autocomplete component)
3. Focus input
4. The menu of options re-displays

Screen.Recording.2026-01-10.at.15.12.35.mov

This PR introduces the reopenOnFocusWhenValid prop so that the appropriate behaviour can be configured.

Its default value is false, meaning no breaking changes and that this can be released as a minor version.

---

Usage

reopenOnFocusWhenValid: true

new oAutocomplete(oAutocompleteElement, {
	…
	reopenOnFocusWhenValid: true,
	…
});

Screen.Recording.2026-01-10.at.15.12.35.mov

---

reopenOnFocusWhenValid: false

new oAutocomplete(oAutocompleteElement, {
	…
	reopenOnFocusWhenValid: false,
	…
});

Screen.Recording.2026-01-10.at.15.07.33.mov

---

reopenOnFocusWhenValid: undefined

new oAutocomplete(oAutocompleteElement, {
	… // i.e. reopenOnFocusWhenValid has not been defined in the props
});

Same as reopenOnFocusWhenValid: false, i.e. false remains the default.

Screen.Recording.2026-01-10.at.15.07.33.mov

---

Dependent PRs

• feat: Add o-autocomplete reopenOnFocusWhenValid option origami#2334

---

References

• https://alphagov.github.io/accessible-autocomplete/examples
• https://alphagov.github.io/accessible-autocomplete/examples/form.html
• GitHub: alphagov / accessible-autocomplete — PR 355: Refinements to address accessibility issues

[andygout]

note: For this PR's CI pipeline to pass, it will need to rebase against the main branch once this other PR has been merged: #46.