HTML <search> element - specification draft and implementation

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 <div role=search>,
• <search action="..."> is a short form of <form role=search action="...">.

The benefit of this element is making the best practice for accessibility simpler, more intuitive and semantically meaningful.

Contents

1. Motivation
   1. Developer experience
2. Design decisions
   1. Form submission
   2. Other form functionality
   3. Nesting
   4. Shadow DOM
   5. Layout
3. Use-cases
4. Specification changes
5. Requests for this feature

Subpages

1. Use-case without form functionality: Satisfying the original proposal.
2. Migration guide, usage patterns
3. Implementation explanation
4. Alternatives
5. Test page
6. What went wrong in the standardization process

Specification draft

• Readable form (generated)
• Specification changes (source)
• Pull request

Implementations

• Chromium (prototype, commits on GitHub)
• WebKit (proof-of-concept, commits on GitHub)
• Firefox in progress (commits in Mercurial)

Motivation

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 search element 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.
• better developer experience

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”.

Developer experience

• KISS: Simplicity of use, learning: matches the established practice.
• No team debates about which element is outside: there’s only one (simpler topology).
• Supports the best practice: the current trend is to render more server-side. Even client-side rendered solutions can benefit from a fallback to SSR when JS loading is unreliable, this is the best practice, superior to pure SPAs.
• Future-proofing: If you have a non-form <search> and one day decide to enable native form submission then all it takes is to add the action attribute. With the <search><form> solution a new level is added to the DOM tree, which can break CSS and JS selectors, traversal logic.

Design decisions

1. <div role=search> is shortened to <search>, form submission is disabled (client-side rendering of search results)
2. <form role=search action="..."> is shortened to <search action="..."> (server-side rendering of search results)
3. <form role=search> becomes <search action> (server-side rendering of search results, target URL is the document’s)

Form submission

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

Other form functionality is opt-in and defined by the form controls. 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, even w/o a form element, controlled by the individual form controls.
• Registering <search> in document.forms has 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

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.

Shadow DOM

• <search> cannot be a shadow root: .attachShadow() is not allowed (like <form>, but unlike <div>). (MDN)

Layout

• form, search { display: block; margin-top: 0; } in the user agent stylesheet (standards mode, no change to quirks mode)

Use-cases

1. 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).
2. Table/dataset filtering: in the main content, typically client-side rendered.
3. 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.

Specification changes

• 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

Requests for this feature

• 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 - “why would an author ever use this new element? Using a <form role="search"> gives you significant functionality beyond the ARIA semantics.”
• tweet - “The semantics of <form role=”search”> is more motivating.”
• 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>?”
• github - “I haven’t run into a need for <div role=”search”> instead of <form role=”search”>”
• 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 would be unlikely to employ <search> without <form>”

Subpages

Due to length these are split:

1. Migration guide, usage patterns
2. Implementation details
3. Alternatives