Add the <search> element

[domenic]

Closes #5811.

Mini-explainer

This new element allows authors to express the semantics of "a set of form controls or other content related to performing a search or filtering operation".

This is an especially desired semantic because it is something that an ARIA landmark role exists for (role="search"), but today can only be expressed with ARIA. Adding a dedicated element allows authors to follow the first rule of ARIA (~ "don't use ARIA if you can avoid it") and is part of the co-evolution process between ARIA and HTML.

Please see the pull request preview for web-developer focused details on usage and examples.

Some notable design choices:

• The name. We were initially a bit concerned that developers would think that this was a type of search input, not a search container. Although we briefly discussed alternative names to combat this like <searcharea>, <searchform>, <searchgroup>, <searchset>, they each had problems, and a quick Twitter poll helped seal the deal that developers would expect and prefer the name <search>. (In addition to other developers chiming in with reasoning on the thread.) See the comments starting at Consider creating an HTML search element #5811 (comment) for more details.

• Like other "block-level" elements, <search> closes any open <p> tags. This ensures an easy transition path from <div role="search"> to <search> and maintains platform consistency.

• Like other "block-level" elements, the user-agent stylesheet for <search> makes it display: block and unicode-bidi: isolate.

• For conformance-checker purposes, the element is categorized as flow content and palpable content, but not sectioning content. (In this respect, it is categorized similarly to <main>, but not like <nav> or <aside>.) We are not sure whether this is ideal, partly because due to Suggest adding a warning about outline algorithm #83 sectioning content is a tricky category. But we believe that the main effect of sectioning content is to encourage authors to add headings inside the sections, which is perhaps not the right default here?

• This element is a straightforward replacement for <div role="search">, and does not come with any additional functionality (such as having form-submission capabilities). Instead it can be combined with other primitives such as <form>, or JavaScript, etc. You can see extensive discussion of this in Consider creating an HTML search element #5811. The reasons for disfavoring more complex solutions are implementer-expressed considerations about complexity and compat risk, as well as web-developer and accessibility community preferences.

Credits

The element description and examples is almost entirely written by @scottaohara, although I made a few edits and rearrangements.

PR merge checklist

• At least two implementers are interested (and none opposed):
  • Chromium is interested
  • Gecko: positive: <search> element mozilla/standards-positions#610
• Tests are written and can be reviewed and commented upon at:
  • Parser: Update html5lib tests web-platform-tests/wpt#39158
  • Rendering: Add rendering tests for the <search> element web-platform-tests/wpt#39163
  • Perhaps the conformance checker test suite should also be updated, /cc @sideshowbarker.
• Implementation bugs are filed:
  • Chrome: https://bugs.chromium.org/p/chromium/issues/detail?id=1294294
  • Firefox: https://bugzilla.mozilla.org/show_bug.cgi?id=1824121
  • Safari: https://bugs.webkit.org/show_bug.cgi?id=254327
  • Validator.nu: <search> element validator/validator#1569
• Dependent specs are ready to update:
  • add the new search element w3c/html-aria#401
  • add proposed search element w3c/html-aam#355
• MDN issue filed: Document the <search> element mdn/mdn#385

(See WHATWG Working Mode: Changes for more details.)

---

/dom.html ( diff )
/grouping-content.html ( diff )
/index.html ( diff )
/indices.html ( diff )
/parsing.html ( diff )
/rendering.html ( diff )
/syntax.html ( diff )

[KittyGiraudel]

Hiiii! ✨ That’s pretty neat—I had no idea this was in the work.

I have a couple questions/comments if that’s okay?

• Is the use of <search> limited to one per page, or can it be used multiple times? The document doesn’t appear to explicitly clarify this.
• In the case it can in fact be used several times on a page, how would a given occurrence be differentiated from another for assistive technologies (e.g. landmark listing)?

I guess where I’m coming at is that if it is not unique per page (unlike <main>), maybe it should be a sectioning element so that it can essentially be labelled? That’s generally what’s recommended for <nav> elements, where we’d encourage authors to label them properly so multiple navigations can be differentiated from one another.

Unless I’m missing something? :)

[scottaohara]

thanks for the comment, @KittyGiraudel. There is definitely guidance that can be added to flesh that out some more.

to quickly answer your questions though:

1. this element is different than <main>, as there can be more than one per document - though as with any landmark that exposes a landmark role, they should be used with purpose. Will draft up some guidance for this.
2. With native HTML alone, the title attribute would be used to name the element, as there is no other mechanism available at this time without using ARIA.

[domenic]

I do think the comparison with <nav> is worth digging into though. I guess you can have multiple of each per page, and the question is whether we want to encourage <hN> children inside of them.

IIUC, for both <nav> and <search>, per https://w3c.github.io/html-aam/#section-elements-and-grouping-content-elements-not-listed-elsewhere you can only use title="" or ARIA. Using a <hN> will not suffice to give an accessible name.

Not sure where that leaves us...

[scottaohara]

have some additional content to add. my initial PR got messed up though, so will give it a shot again later.

[Kaleidea]

(edited by @domenic) Off-topic: see discussion in #5811 (comment)

I'd like to thank the editors' work on this proposal and their long-term service towards the web developer community. However, [there is a viable alternative](https://github.com//issues/7323) with improved API ergonomy that better serves developer needs, but wasn't considered. In my opinion ignoring that alternative would be a missed opportunity to improve developer satisfaction and the quality of the World Wide Web.

Opposition

Since this is a low priority feature, there is no need to rush to a solution without giving due consideration for all needs and use-cases, therefore I have to oppose this proposal in this form at this time. Due to discourtesy and the rejection to discuss the alternative of aliasing <form>, I've appealed the decisions to the Steering Group. I hope their guidance will help achieve an outcome that serves more developers' needs.

[zcorpan]

cc @whatwg/html-parser for

Does not close <p> elements, i.e. does not require any parser changes. (Note: this is unlike <main>.) Implementers are generally not excited about parser changes and I don't think auto-closing <p> elements is a big enough win.

Is it OK for new "block" elements to not close <p>?

If it is, maybe we need to reconsider if </p> should be optional, since it will be very confusing to not be able to omit it inside or before <search>.

[artalar]

It would be nice to have main property for this element, which indicate to browser that it should be used as a main search for site when user click ctrl(command)+F. It may dramatically improve user search experience for sites with virtual lists.

[Kaleidea]

It would be nice to have main property for this element, which indicate to browser that it should be used as a main search for site when user click ctrl(command)+F. It may dramatically improve user search experience for sites with virtual lists.

@artalar I think that would be a separate proposal to hook and redirect the browser's CtrlCmd-F search functionality to the marked search element on the page, it's more than what this proposal aims for. Currently CtrlCmd-F search can be hooked with JS.

[Kaleidea]

cc @whatwg/html-parser for

Does not close <p> elements, i.e. does not require any parser changes. (Note: this is unlike <main>.) Implementers are generally not excited about parser changes and I don't think auto-closing <p> elements is a big enough win.

Is it OK for new "block" elements to not close <p>?

@zcorpan Adding the element requires 2 changes to the WebKit & Blink parsers in the HTMLTreeBuilder class:
commit.

Making it a paragraph closing element requires 2 more trivial changes:
commit.

OTOH if <search> is not closing paragraphs then the trivial transformation from <div role=search> -> <search> will break in cases like:
<p> Paragraph ends here. <div role=search> ... </div>
will not be equivalent to:
<p> Paragraph ends here. <search> ... </search>
Such inconsistency can be a difficulty for dev tool developers (eg. automated migration to <search>) and a footgun for web developers.

Note: I don't like the optional </p> either, but changing it would break the web.

[zcorpan]

OTOH if <search> is not closing paragraphs then the trivial transformation from <div role=search> -> <search> will break in cases like: <p> Paragraph ends here. <div role=search> ... </div> will not be equivalent to: <p> Paragraph ends here. <search> ... </search> Such inconsistency can be a difficulty for dev tool developers (eg. automated migration to <search>) and a footgun for web developers.

I agree, and it will be a persistent footgun. I think it's probably better in the long run to change the parser when adding a new block element.

[domenic]

@hsivonen any updates on your thoughts about whether it's OK to have <search> close <p> tags?

[hsivonen]

If a <search> element is added, making it close <p> is probably the right thing to do. I'm not convinced that adding the <search> element is worthwhile, since it doesn't add expressiveness but mainly addresses a principled concern that all of ARIA should be ported to HTML in non-ARIA form, but I don't know enough about the use cases to argue strongly in favor or agains..

[zcorpan]

Also rendering tests.

web-platform-tests/wpt#39163

[zcorpan]

OK I think this is ready now, modulo review of the rendering tests.

[annevk]

I suggest we let @domenic do the honors since it's been well over a year since we started all this and he might well have some other relevant insights.

[domenic]

Thank you all for helping push this over the finish line!! I think it's ready to merge. I'll also file an MDN bug.