Research into role=searchbox. Where and how is role searchbox meant to be used?

[LaurenceRLewis]

I have researched the ARIA issues and specification related to the searchbox role and there seems to be no clarity around its usage.
In my workplace I am finding developers are applying it in various way because of this lack of guidance in the ARIA documentation.

As an accessibility tester (Accessibility Senior Specialist) I would like to understand the role and how this should best be conveyed to developers.

If there is a draft or other example of using the role searchbox, either with a listbox popup or other method of providing search results, please let me know the link. Otherwise I would appreciate guidance on how this role is meant to be used in a search type component.

Thanks.

References and comments:

ARIA 1.2 Role Searchbox specification
A type of textbox intended for specifying search criteria. See related textbox and search.
Base Concept: <input[type="search"]> in [HTML]

Authoring Practices Guide entry for role searchbox #1115
carmacleod commented on Jul 27, 2019
"There is already a search section and example in the APG. It's in the landmarks section.
Guidance: http://w3c.github.io/aria-practices/#aria_lh_search
Example: http://w3c.github.io/aria-practices/examples/landmarks/search.html

Also, in case it's helpful, there's a search example being developed in the Web Accessibility Tutorials:
https://w3c.github.io/wai-tutorials/ideas/search/"

In this issue the links provided the Guidance and Example relate to role=search and not role=searchbox. The search example link is broken.

mcking65 commented on Aug 31, 2019
"We do not yet know what kind of guidance we will provide for the searchbox role in the APG."

Extending guidance for comboboxes that use searchbox role #1158

After much discussion that has no conclusion, only opinion and observation, "mcking65 commented on Nov 20, 2019"
"searchbox is no longer a possible part of the combobox pattern."

Revise combobox design pattern to reflect ARIA 1.2 requirements #1250

There is no guidance on combobox vs searchbox and the only reference to searchbox is @mcking65 mcking65 mentioned this issue on Nov 20, 2019 as a reference back to "Extending guidance for comboboxes that use searchbox role #1158"

[JAWS-test]

I don't understand your question. searchbox is an input field for search. As far as I know, it cannot be used with combobox.

[LaurenceRLewis]

@JAWS-test I am seeing the searchbox role being used in place of role combobox and in other ways. As I cannot find clarification in using the role I am seeking a clear understanding of how it is intended to be implemented.

[StommePoes]

It appears that it's for when devs insist on turning this
<input type="search">
into this
<div tabindex="0" aria-label="search" role="searchbox">
which, it would not surprise me if users don't hear a difference with that from
<div tabindex="0" aria-label="search" role="textbox">

In all the 1.2 combobox examples, the input inside is getting the combobox role (it's no longer on a wrapper). This means devs cannot use the searchbox role, because what little there is out there about searchboxes says it's a role for the focusable thingie itself and I would imagine if you did not use combobox on something functioning as a combobox then you'd lose all comboboxness.

I would tell developers if users can't tell it's for searching, they have crappy labels/instructions. It looks like searchbox, if it truly still exists, is solely for fake inputs and not more complex widgets.

The small mention I see in the spec doesn't mention anything about widgets so I'm going to guess the confusion by devs is because in the past (like the current 1.1 stuff) have combobox on the wrapper and textbox role on the input... so they're thinking, "well it's not just a textbox, it's the subtype searchbox" and so are using searchbox on the inputs.
But since we know the 1.1 combobox was a wailing-and-gnashing-of-teeth thing, it seems we should direct devs to the 1.2 combobox and forget about searchbox roles for those. Maybe the spec could be clearer in the combobox section but the searchbox section seems clear (equiv to input type="search" only).

[LaurenceRLewis]

So any component that acts like a combobox with a listbox pop up (ARIA1.2 implementation), which I have been recommending for many years thanks to @accdc, should be exactly that.

Role searchbox is implemented as div role searchbox etc. And submitting this adds a list of link results in the page/new page whatever. It does not pop up a listbox.

@StommePoes once again your vocabulary has me smiling 😀

[JAWS-test]

Small note: In HTML I can combine type=search with list and datalist. This is not possible in ARIA due to the limitations of combobox.

But that doesn't seem to be a problem to me, because type=search and searchbox are anyway only output as normal input field (i.e. like type=text, textbox) by the screen readers I know.

[StommePoes]

But that doesn't seem to be a problem to me, because type=search and searchbox are anyway only output as normal input field (i.e. like type=text, textbox) by the screen readers I know.

Yeah I can't remember ever hearing anything special when running into those... and I only recall people wanting to use type=search because specifically Safari would offer users this cute useless little "x" inside the then-bubblegum-aqua-teen-hunger-force-style fluffy inputs that I guess you could click with a mouse to clear your search terms.

[LaurenceRLewis]

I have been looking at the spec again and I still have some confusion.

If role searchbox is equivalent to <input type="search". Why does the role include the Inherited States and Properties: aria-activedecendent, aria-haspopup, aria-controls, which are the same attributes as role combobox.

If role searchbox cannot be used as combobox, why does it include these inherited states and properties?

So I don’t understand why role searchbox and role combobox are not interchangeable if searchbox is equivalent to <input type="search", and both inherit the same states and properties.

This is why developers use searchbox interchangeable with combobox and don’t consider the basic usage that role searchbox = HTML <input type search.

[StommePoes]

Why does the role include the Inherited States and Properties: aria-activedecendent, aria-haspopup, aria-controls, which are the same attributes as role combobox.

It might very well be due to the old combobox pattern from the 1.1 Authoring Practices, which had combobox role on a wrapper and textbox on the input inside, and the input had those other attributes.

So if searchbox still has these listed in a draft spec (since 1.2 Authoring Practices are still draft right now as well), maybe this ticket should remain open until that's changed.
Not sure who best to ping on that. @ZoeBijl ?

[LaurenceRLewis]

@accdc
@mcking65
@jnurthen

searchbox role
https://www.w3.org/TR/wai-aria-1.2/#searchbox

[LaurenceRLewis]

The following search I believe demonstrates correct use of role searchbox

Correct use of role searchbox

Select the Search link top of the screen. Position screen image below. (Can't find a way to add ALT text to the image)

[accdc]

I agree this is confusing, and we are going to have to address the differences at some point to clarify it, though I'm not sure where as yet. E.G. A note in the ARIA spec or the APG. As far as I've always understood, textbox and searchbox were basically the same thing, other than that searchbox was meant to go inside a role=search region for site search sections, primarily to handle autosuggest functionality that often occurs in many such controls (see google.com :) though searchbox is not used there). For a while there was even similar behavior with role=textbox, where on popular sites like linkedin, facebook, and twitter, the comments edit fields would cause autosuggest listboxes to appear if certain character combos were used, such as hash tags and so on, which completely destroyed the accessibility of any screen reader actually trying to write within that field since aria-activedescendant was often used in combination with this, thus making it impossible to even hear or review what you were typing into those fields. Thankfully they all appear to have stopped doing that in recent years,. Even so, the spec mappings still have remnants that tie into these old and terrible implementations. So yes, I agree this is about as clear as mud and should be made clearer in the future to make using these controls more reliable going forward.

[jnurthen]

My understanding
For the purposes of a11y apis
role="searchbox" === <input type="search">
role="textbox" === <input type="text">

There is no difference between them other than the expectation (on some platforms) that a searchbox might cause a clear button to be rendered when it contains text.

I don't believe I have ever used role="searchbox" as it provides very little benefit but conversely if used correctly I don't think it has many downsides either.

Looking at Core-aam the only difference in the mappings are extra object attributes (on most platforms) and a sub-role (on Apple). Looking at the Chrome source code I see they add an internal roledescription ("search box" on windows, "search text field" everywhere else, which is used - but otherwise I believe it acts exactly like a text box

I don't think search has ever had any indiction that it does or doesn't perform auto-suggest.

[JAWS-test]

@LaurenceRLewis

Why does the role include the Inherited States and Properties: aria-activedecendent, aria-haspopup, aria-controls, which are the same attributes as role combobox.

I think because these attributes can also be used with textbox and many other roles and are not limited to combobox. I can use aria-activedescendant for example with textbox and searchbox for the autocomplete suggestions (without using a combobox)

A second reason: searchbox inherits these attributes from textbox. If textbox should have more attributes than searchbox, because textbox can be used with combobox and searchbox cannot, then the hierarchy of ARIA roles no longer works correctly at that point

[mcking65]

@LaurenceRLewis

A searchbox is nothing more than a textbox that might be announced as "search box", "search edit", or "search field" by some screen readers. Because it may be announced with one of those roles, it would be redundant to include the word "Search" in the accessible name.

For example, on the Telstra site, JAWS reads the search input as:

Search telstra.com �Search edit

In that example, because the accessible name is "Search telstra.com", using the searchbox role just added some extra verbosity that arguably makes the experience worse.

Presumably, because assistive technologies know the input is for search, they could provide a function for helping users locate any available search input. Thus, one could argue that use of role searchbox or the HTML ssearch input type brings the page closer to some ideal related to WCAG 1.3.5 (Identify Input Purpose). However, in the Telstra case, assistive technologies would not be able to locate it directly because the search input is hidden behind a disclosure, which, BTW, is incorrectly implemented with a link instead of a button.

@StommePoes, Note that:

<div tabindex="0" aria-label="search" role="searchbox">

1. Would need contenteditable.
2. Would be announced as "Search searchbox".

As @JAWS-test and @jnurthen pointed out, there is no specific expectation that a searchbox either does or does not provide suggestions for values for the input, i.e., autocomplete.

ARIA supports autocomplete functionality for any kind of text input. I helped author the ARIA 1.1 changes to aria-controls, aria-activedescendant, and aria-autocomplete to allow this. This is essential to support things like mentions in text areas, such as this GitHub comment composer.

So, since a searchbox is a text input, you could make it work just like an editable combobox. Just follow the 1.2 combobox pattern but give the text input role searchbox instead of role combobox. Screen readers should (but might not) announce the availability of autocomplete. Again, this has dubious value at this time, but it is certainly permitted and would likely work just as well as any combobox save the verbosity concern I expressed above.

In short:

1. At this time, the searchbox role does not provide any clear benefits to users, and it may create unwelcome verbosity in some circumstances.
2. Support for attributes related to autocomplete is intentional, and there is no reason to avoid using them in combination with the searchbox role.

[LaurenceRLewis]

@mcking65 thank you for this complete explanation. Closing.