This is the proposed specification and implementation of the search element following the best practice usage (MDN, WAI-ARIA), as requested by developers. It covers both usage patterns: server-side and client-side rendering of the search results.

• Specification draft:
  • Readable form (generated)
  • Specification changes (source, see below)
• Implementations (proof-of-concept):
  • Chromium (commits on GitHub)
  • WebKit (commits on GitHub)
  • Firefox in progress (commits in Mercurial)
• Implementation explanation

Contents

1. Specification changes
2. Motivation
3. Feature definition
4. Use-cases
5. Requests for this feature
6. Prior art

Subpages

1. Migration guide, usage patterns
2. Implementation details
3. Including the original proposal: <div> functionality
4. Alternatives

Specification changes

• Readable form (generated)
• 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
• Breakdown of changes: each commit contains a different transformation pattern for quicker (batched) verification of the systematic changes.

Motivation

The <search> element with form functionality is

• a popular developer request (see below: Requests for this feature)
• 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.

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

Feature definition

1. <div role=search> is shortened to <search>, form submission is disabled
2. <form role=search action="..."> is shortened to <search action="...">

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 is migrated to <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> 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 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.

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.

Requests for this feature

• 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>"

Prior art

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.

Subpages

Due to length these are split:

1. Migration guide, usage patterns
2. Implementation details
3. Including the original proposal: <div> functionality
4. Alternatives