The <search> element is a new semantic HTML element to mark the ARIA search landmark. It represents the common functionality of searching a website, contents on a webpage or filtering a dataset. <search> is a short form of <form role=search> or <div role=search> depending on whether form submission is enabled by setting the action attribute. The benefit of this element is making the best practice for accessibility simpler, more intuitive and semantically meaningful.
- Test page
- Implementation explanation
- Specification draft:
- Readable form (generated)
- Specification changes (source)
- Pull request
- Implementations:
- Migration guide, usage patterns
- Implementation details
- Including the original proposal:
<div>functionality - Alternatives
- Readable form (generated)
- Breakdown of changes - pull request: each commit is a different transformation pattern for quicker (batched) verification of the systematic editorial changes.
- Categorised changes (source):
- What developers will read: "The search element" section
- Add the
<search>element to tag lists - Systematic changes: Rewording "form elements" -> "forms", etc.
- Optional: Clarification notes
The <search> element with form functionality is
- a popular developer request
- the best practice as demonstrated by the MDN example and the WAI-ARIA example.
- the common sense mental model: "The
searchelement represents a part of a document or application that contains a set of form controls or other content related to performing a search or filtering operation." A set of form controls is a form.
This approach meets developers' expectations, guaranteeing the best API ergonomy. In the long term this will reduce the learning curve, increase developer satisfaction, make accessibility more intuitive and consequently improve the quality of the World Wide Web. These long-term benefits are worth the little extra effort up front, which is mostly a systematic, trivial rewording of the "Forms" section in the HTML specification to refer to "form" instead of "form element".
<div role=search>is shortened to<search>, form submission is disabled (client-side rendering of search results)<form role=search action="...">is shortened to<search action="...">(server-side rendering of search results)<form role=search>becomes<search action>(server-side rendering of search results, target URL is the document's)
Form submission is when the browser sends the contents of a form to a server and navigates to the webpage in the response. This includes implicit form submission which happens when pressing ENTER (or equivalent) or the first submit button.
In the first case (div) form submission is an unwanted feature, therefore disabled. The second case behaves equivalently to a form with role=search.
The action attribute's presence distinguishes between the two cases. A form without the action attribute becomes <search action="">, this slightly alters the specification of the action attribute on the search element.
Alternatives considered: method=none / nosubmit boolean attribute. To support the migration of the div usage without adding extra attributes the absence of action must disable form submission, therefore the alternatives would be redundant.
Other form functionality is opt-in: if the developer makes no use of it then it does not change the application's behavior.
- Form validation is optional.
- Reset button is optional.
- Autocomplete is on by default for
<input type=searchbox>even without a form. - Registering
<search>indocument.formshas no effect on behavior. - Associating with descendant form controls has no effect on behavior unless the developer makes use of it, in which case it is a benefit.
Nesting of <search> and <form> is invalid in any combination:
<search><search>is semantically meaningless.<div role=search>...<form>and<form>...<div role=search>can often be refactored to a single<search>. Researching usage patterns in the wild suggests this to be possible in most cases.
<search>cannot be a shadow root:.attachShadow()is not allowed (like<form>, but unlike<div>). (MDN)
form, search { display: block; margin-top: 0; }in the user agent stylesheet (standards mode, no change to quirks mode)
- Site search: typically in the header/sidebar, providing a pop-up list of suggestions (client-side rendered), navigating to a results page (server-side rendered).
- Table/dataset filtering: in the main content, typically client-side rendered.
- Page search (eg. text editor): changes positioning and selection client-side.
The most common use-case for a <search> element is site search. The best practice for implementation is <form role="search" action="/search">. Exception to this is client-side rendered search results (use-cases without page navigation). In that case a site search page (also advertised in sitesearch.xml) can be used as a no-JS fallback. JS execution cannot be taken for granted, therefore a fallback improves availability in case of unreliable internet or disabled JS.
- tweet - "Using a
<form role="search">gives you significant functionality beyond the ARIA semantics." - tweet - "Should the
<search>element be an extension of the<form>element such that it can process its own form actions without having to also be wrapped in a<form>?" - tweet - "<search> makes sense and would be great if [...] it could process its own form actions without a <form>. I would expect that feature would make (correct) usage of the element by devs more likely too"
- tweet - "The semantics of <form role="search"> is more motivating."
- tweet - "Aren't you meant to add
role="search"to the<form>element rather than a separate element?" - tweet - "Extra attribute on a <form>?"
- github - "I haven't run into a need for <div role="search"> instead of <form role="search">"
- github - "I would be unlikely to employ
<search>without<form>"
This proposal builds upon the request for the <search> element implementing <div role=search>. The decisions made there that don't affect form functionality also apply here:
search { display: block }in the user agent stylesheet- Is it a paragraph closing element? Implementation cost: 2 lines of code.
Due to length these are split:
- Migration guide, usage patterns
- Implementation details
- Including the original proposal:
<div>functionality - Alternatives