Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

HTML <search> element #27727

Merged
merged 6 commits into from
Jul 10, 2023
Merged

HTML <search> element #27727

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
2427213
HTML `<search>` element
ramiy Jul 3, 2023
1c32564
Fix lint issues
ramiy Jul 3, 2023
ef43dac
Apply suggestions from code review
ramiy Jul 8, 2023
056ad42
lint
ramiy Jul 8, 2023
0b98a6f
Merge branch 'main' into html-search-element
ramiy Jul 9, 2023
45769cd
ran prettier
estelle Jul 10, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions files/en-us/web/html/element/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,7 @@ Content sectioning elements allow you to organize the document content into logi
| {{HTMLElement("main")}} | Represents the dominant content of the body of a document. The main content area consists of content that is directly related to or expands upon the central topic of a document, or the central functionality of an application. |
| {{HTMLElement("nav")}} | Represents a section of a page whose purpose is to provide navigation links, either within the current document or to other documents. Common examples of navigation sections are menus, tables of contents, and indexes. |
| {{HTMLElement("section")}} | Represents a generic standalone section of a document, which doesn't have a more specific semantic element to represent it. Sections should always have a heading, with very few exceptions. |
| {{HTMLElement("search")}} | Represents a part that contains a set of form controls or other content related to performing a search or filtering operation. |

## Text content

Expand Down
161 changes: 161 additions & 0 deletions files/en-us/web/html/element/search/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,161 @@
---
title: "<search>: The generic search element"
slug: Web/HTML/Element/search
page-type: html-element
browser-compat: html.elements.search
---

{{HTMLSidebar}}

The **`<search>`** [HTML](/en-US/docs/Web/HTML) element is a container representing the parts of the document or application with form controls or other content related to performing a search or filtering operation. The `<search>` element semantically identifies the purpose of the element's contents as having search or filtering capabilities. The search or filtering functionality can be for the website or application, the current web page or document, or the entire Internet or subsection thereof.

## Attributes

This element only includes the [global attributes](/en-US/docs/Web/HTML/Global_attributes).

## Usage notes

The `<search>` element is not for presenting search results. Rather, search or filtered results should be presented as part of the main content of that web page. That said, suggestions and links that are part of "quick search" functionality within the search or filtering functionality are appropriately nested within the contents of the `<search>` element as they are search features.

## Examples

### Header search form

This example demonstrates the use of `<search>` as the container for a search within a website header to perform a simple site-wide search. The `<search>` is a semantic container for the {{HTMLElement("form")}} that submits the user-entered search query to a server.

#### HMTL

```html
<header>
<h1>Movie website</h1>
<search>
<form action="./search/">
<label for="movie">Find a Movie</label>
<input type="search" id="movie" name="q" />
<button type="submit">Search</button>
</form>
</search>
</header>
```

#### Result

{{EmbedLiveSample('Header search form')}}

### Web app search

This example demonstrates potential DOM content when dynamically including JavaScript search functionality in a web application. When search functionality is implemented entirely with JavaScript, if no form is submitted, neither a {{HTMLElement("form")}} element nor a submit {{HTMLElement("button")}} is required. For semantics, the `<search>` element is included to contain the search and filtering capabilities.

#### HMTL

```html
<search>
<label>
Find and filter your query
<input type="search" id="query" />
</label>
<label>
<input type="checkbox" id="exact-only" />
Exact matches only
</label>

<section>
<h3>Results:</h3>
<ul id="results">
<!-- search result content -->
</ul>
<output id="no-results">
<!-- no results content -->
</output>
</section>
</search>
```

#### Result

{{EmbedLiveSample('Web app search')}}
ramiy marked this conversation as resolved.
Show resolved Hide resolved

> **Note:** Remember that some users don't have JavaScript, and none of your users have JavaScript running until the JavaScript is successfully downloaded, parsed, and executed, ensure your users can access the content of your site with JavaScript disabled.

### Multiple searches

This example demonstrates a page with two search features. The first is a global site search located on the header. The second is a search and filter based on the page context, in our example a car search.

#### HMTL

```html
<body>
<header>
<h1>Car rental agency</h1>
<search title="Website"> ... </search>
</header>
<main>
<h2>Cars available for rent</h2>
<search title="Cars">
<h3>Filter results</h3>
...
</search>
<article>
<!-- search result content -->
</article>
</main>
</body>
```

#### Result

{{EmbedLiveSample('Multiple searches')}}

## Technical summary

<table class="properties">
<tbody>
<tr>
<th scope="row">
<a href="/en-US/docs/Web/HTML/Content_categories">Content categories</a>
</th>
<td>
<a href="/en-US/docs/Web/HTML/Content_categories#flow_content">Flow content</a>, <a href="/en-US/docs/Web/HTML/Content_categories#palpable_content">palpable content</a>.
</td>
</tr>
<tr>
<th scope="row">Permitted content</th>
<td>
<a href="/en-US/docs/Web/HTML/Content_categories#flow_content">Flow content</a>.
</td>
</tr>
<tr>
<th scope="row">Tag omission</th>
<td>{{no_tag_omission}}</td>
</tr>
<tr>
<th scope="row">Implicit ARIA role</th>
<td>
<code><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/search_role">search</a></code>
</td>
</tr>
<tr>
<th scope="row">Permitted ARIA roles</th>
<td>
<a href="/en-US/docs/Web/Accessibility/ARIA/Roles/form_role"><code>form</code></a>, <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/group_role"><code>group</code></a>, <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/none_role"><code>none</code></a>, <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role"><code>presentation</code></a>, <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/region_role"><code>region</code></a>, <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/search_role"><code>search</code></a>
</td>
</tr>
<tr>
<th scope="row">DOM interface</th>
<td>{{domxref("HTMLElement")}}</td>
</tr>
</tbody>
</table>

## Specifications

{{Specifications}}

## Browser compatibility

{{Compat}}

## See also

- Other search-related elements: {{HTMLElement("header")}}, {{HTMLElement("footer")}}, {{HTMLElement("aside")}}, {{HTMLElement("nav")}}, {{HTMLElement("form")}}
- [ARIA: Search role](/en-US/docs/Web/Accessibility/ARIA/Roles/search_role)
2 changes: 1 addition & 1 deletion files/en-us/web/html/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ page-type: landing-page

"Hypertext" refers to links that connect web pages to one another, either within a single website or between websites. Links are a fundamental aspect of the Web. By uploading content to the Internet and linking it to pages created by other people, you become an active participant in the World Wide Web.

HTML uses "markup" to annotate text, images, and other content for display in a Web browser. HTML markup includes special "elements" such as {{HTMLElement("head")}}, {{HTMLElement("title")}}, {{HTMLElement("body")}}, {{HTMLElement("header")}}, {{HTMLElement("footer")}}, {{HTMLElement("article")}}, {{HTMLElement("section")}}, {{HTMLElement("p")}}, {{HTMLElement("div")}}, {{HTMLElement("span")}}, {{HTMLElement("img")}}, {{HTMLElement("aside")}}, {{HTMLElement("audio")}}, {{HTMLElement("canvas")}}, {{HTMLElement("datalist")}}, {{HTMLElement("details")}}, {{HTMLElement("embed")}}, {{HTMLElement("nav")}}, {{HTMLElement("output")}}, {{HTMLElement("progress")}}, {{HTMLElement("video")}}, {{HTMLElement("ul")}}, {{HTMLElement("ol")}}, {{HTMLElement("li")}} and many others.
HTML uses "markup" to annotate text, images, and other content for display in a Web browser. HTML markup includes special "elements" such as {{HTMLElement("head")}}, {{HTMLElement("title")}}, {{HTMLElement("body")}}, {{HTMLElement("header")}}, {{HTMLElement("footer")}}, {{HTMLElement("article")}}, {{HTMLElement("section")}}, {{HTMLElement("p")}}, {{HTMLElement("div")}}, {{HTMLElement("span")}}, {{HTMLElement("img")}}, {{HTMLElement("aside")}}, {{HTMLElement("audio")}}, {{HTMLElement("canvas")}}, {{HTMLElement("datalist")}}, {{HTMLElement("details")}}, {{HTMLElement("embed")}}, {{HTMLElement("nav")}}, {{HTMLElement("search")}}, {{HTMLElement("output")}}, {{HTMLElement("progress")}}, {{HTMLElement("video")}}, {{HTMLElement("ul")}}, {{HTMLElement("ol")}}, {{HTMLElement("li")}} and many others.

An HTML element is set off from other text in a document by "tags", which consist of the element name surrounded by "`<`" and "`>`". The name of an element inside a tag is case-insensitive. That is, it can be written in uppercase, lowercase, or a mixture. For example, the `<title>` tag can be written as `<Title>`, `<TITLE>`, or in any other way. However, the convention and recommended practice is to write tags in lowercase.

Expand Down