# Search A search bar lets people enter a query and find matching results, with a search view that shows suggestions and results. **Example: A search bar with recipe suggestions** ```html ``` ## Usage guidelines * **Use it to navigate with queries.** Search is the entry point for finding content in a product by typing. * **Hint what to search.** A bar can show hinted text such as "Search recipes", a leading icon and up to two [trailing](#trailing-elements) icons. * **Suggest as people type.** The view lists suggestions or results below the bar as the query changes. * **Choose a style.** The contained style is recommended; the [divided](#divided) style puts a divider between the header and the results. * **Make it prominent.** A [search app bar](#search-app-bar) gives search an emphasized, global entry point. This component is new in [M3 Expressive](https://m3.material.io/blog/building-with-m3-expressive). ## Anatomy A search bar holds the leading and trailing elements; its default slot holds the suggestions or results shown in its search view. **Example: A search bar with leading, trailing and view trailing buttons and suggestions** ```html

mic

``` ## Examples ### Trailing elements Put up to two icon buttons in the `trailing` slot, or an avatar in the `avatar` slot. A `leading` icon button, such as a menu button, replaces the default search icon. **Example: A search bar with a menu button and a voice search button** ```html

mic

``` ### Docked Add `docked` to open the view as a drop-down below the bar, for medium and larger windows. Without it, the view opens full-screen. **Example: A docked search bar** ```html ``` ### Divided Add `divided` to use the baseline style, with a divider between the view's header and its results. **Example: A search bar with a divided view** ```html ``` ### Search app bar Put a search bar in the `search` slot of an [app bar](/material-web/3.0/components/app-bar/) with `variant="search"`. The app bar draws the container, so make the bar's container transparent. **Example: A search app bar with a profile button** ```html

account_circle

``` ### Standalone search view Use `md-gb-search-view` on its own for a search that opens from an icon button. Set `open` from the button. **Example: An icon button that opens a search view** *HTML* ```html

``` *JavaScript* ```js document.querySelector('#open-search').addEventListener('click', () => { document.querySelector('#recipes').open = true; }); ``` ### Searching Set `searching` while you wait for results. The view shows a progress indicator and marks the results as busy. **Example: A search bar that shows it is searching for a second** *HTML* ```html ``` *JavaScript* ```js const bar = document.querySelector('md-gb-search-bar'); const loadResults = (query) => new Promise((resolve) => setTimeout(resolve, 1000)); bar.addEventListener('search', async (event) => { bar.searching = true; await loadResults(event.detail.value); bar.searching = false; }); ``` ## Accessibility * The bar's input and the view's input are comboboxes, and the suggestions are the options of a `listbox`. Slotted results without a role get `role="option"`. * Enter, the Down arrow or typing opens the view. The back button and Escape close it. * The input is named by `label`, which defaults to `placeholder`. Set `label` when the hint isn't a good name. * Give icon buttons in the slots an `aria-label`, such as "Voice search". * Change `back-label`, `clear-label`, `results-label` and `searching-label` when you translate the page. Announce changing results with `suggestions-label`. ## API reference ### <md-gb-search-bar> A Material Design search bar. #### Properties | Property | Attribute | Type | Default | | --- | --- | --- | --- | | backLabel
Accessible label of the view's back button. | back-label | string | 'Back' | | clearLabel
Accessible label of the view's clear button. | clear-label | string | 'Clear search' | | disabled
Whether the search bar is disabled. | disabled | boolean | false | | divided
Uses the divided (baseline) view style. | divided | boolean | false | | docked
Opens the view docked below the bar, for medium and larger windows. Otherwise it opens full-screen. | docked | boolean | false | | expanded
Whether the search view is open. | expanded | boolean | | | label
Accessible label of the inputs. Defaults to placeholder, per the spec. | label | string | '' | | placeholder
Hinted search text, e.g. "Search messages". | placeholder | string | '' | | quick
Whether to skip the open and close animations. | quick | boolean | false | | resultsLabel
Accessible label of the results listbox. | results-label | string | 'Search results' | | searching
Whether the app is searching: shows progress in the view. | searching | boolean | false | | searchingLabel
Accessible label of the searching progress indicator. | searching-label | string | 'Searching' | | suggestionsLabel
Announced when suggestions or results become available. | suggestions-label | string | 'Suggestions available' | | value
The search text. Shared with the view. | value | string | '' | #### Slots | Slot | Description | | --- | --- | | default | Search suggestions or results, shown in the view. Use elements with role="option"; slotted elements without a role get it. | | avatar | A trailing avatar image. | | leading | A navigation icon button. Defaults to a non-functional search icon. | | trailing | Up to two trailing icons or icon buttons. | | view-trailing | Trailing icon buttons in the view's header. | #### Events | Event | Description | | --- | --- | | change
Event | Fired when the search text is committed. | | close
CustomEvent<{reason: string}> | Fired when the view begins closing. Cancelable. | | closed
CustomEvent<{reason: string}> | Fired when the view has closed. | | input
InputEvent | Fired when the search text changes. | | open
Event | Fired when the view begins opening. Cancelable. | | opened
Event | Fired when the view has opened and animations finished. | | search
CustomEvent<{value: string}> | Fired when a search is executed with Enter in the view. | #### Methods | Method | Description | | --- | --- | | close
(reason?: string) => Promise<void> | Closes the search view. | | focus
(options?: FocusOptions) => void | Focuses the search bar input. | | render
() => TemplateResult<1> | Invoked on each update to perform rendering tasks. This method may return any value renderable by lit-html's ChildPart - typically a TemplateResult. Setting properties inside this method will *not* trigger the element to update. | | show
() => Promise<void> | Opens the search view. | #### CSS parts | Part | Description | | --- | --- | | ::part(bar) | The search bar container. | | ::part(input) | The search bar input. | | ::part(view) | The md-gb-search-view. | #### CSS custom properties | Property | Description | | --- | --- | | --avatar-shape | Avatar shape. | | --avatar-size | Avatar size. | | --contained-avatar-target-size | Avatar tap target size. | | --contained-icon-label-gap | Space between the icon targets and the input. | | --contained-leading-margin | Recommended margin to the start of the window. | | --contained-leading-space | Space before the leading icon target. | | --contained-motion-duration | Expand and collapse duration. | | --contained-motion-spring | Expand and collapse easing. | | --contained-no-actions-leading-space | Leading space without a leading icon. | | --contained-no-actions-trailing-space | Trailing space without trailing icons. | | --contained-trailing-actions-gap | Gap between trailing icon targets. | | --contained-trailing-actions-leading-space | Space before the trailing icon targets. | | --contained-trailing-actions-trailing-space | Space after the trailing icon targets. | | --contained-trailing-margin | Recommended margin to the end of the window. | | --contained-trailing-space | Trailing space. | | --container-color | Container color. | | --container-height | Container height. | | --container-shape | Container shape. | | --icon-size | Icon size. | | --icon-target-size | Icon tap target size. | | --input-text | Input typography. | | --input-text-axes | Input font variation settings. | | --input-text-color | Input text color. | | --input-text-tracking | Input letter spacing. | | --leading-icon-color | Leading icon color. | | --leading-icon-leading-icon-label-space | Divided style space between the leading icon and input. | | --leading-space | Divided style leading space. | | --max-width | Maximum width. | | --min-width | Minimum width. | | --supporting-text | Placeholder typography. | | --supporting-text-axes | Placeholder font variation settings. | | --supporting-text-color | Placeholder color. | | --supporting-text-tracking | Placeholder letter spacing. | | --trailing-icon-color | Trailing icon color. | | --trailing-icon-label-trailing-icon-space | Divided style space between the input and trailing icon. | | --trailing-space | Divided style trailing space. | ### <md-gb-search-view> Focused search: suggestions or results opened from a search bar. #### Properties | Property | Attribute | Type | Default | | --- | --- | --- | --- | | backLabel
Accessible label of the back button. | back-label | string | 'Back' | | bar
The search bar the view expands from. Docked, the view is positioned over it. | | HTMLElement | null | | clearLabel
Accessible label of the clear button. | clear-label | string | 'Clear search' | | divided
Divided (baseline) style, with a divider between the header and results. Otherwise the view uses the contained M3 Expressive style. | divided | boolean | false | | docked
Docked layout: a drop-down below the search bar over a scrim. Otherwise the view is full-screen. | docked | boolean | false | | label
Accessible label of the input and dialog. Defaults to placeholder. | label | string | '' | | open
Whether the view is open. | open | boolean | | | placeholder
Hinted search text. | placeholder | string | '' | | quick
Whether to skip the open and close animations. | quick | boolean | false | | resultsLabel
Accessible label of the results listbox. | results-label | string | 'Search results' | | searching
Whether the app is searching: shows a progress indicator under the header and marks the results busy for assistive technology. | searching | boolean | false | | searchingLabel
Accessible label of the searching progress indicator. | searching-label | string | 'Searching' | | suggestionsLabel
Announced when suggestions or results become available. | suggestions-label | string | 'Suggestions available' | | value
The search text. | value | string | '' | #### Slots | Slot | Description | | --- | --- | | default | Search suggestions or results. | | leading | Replaces the back icon button. | | trailing | Trailing icons or icon buttons, after the clear button. | #### Events | Event | Description | | --- | --- | | change
Event | Fired when the input text is committed. | | close
CustomEvent<{reason: string}> | Fired when the view begins closing. Cancelable. See SEARCH_CLOSE_REASONS. | | closed
CustomEvent<{reason: string}> | Fired when the view has closed. | | input
InputEvent | Fired when the input text changes. | | open
Event | Fired when the view begins opening. Cancelable. | | opened
Event | Fired when the view has opened and animations finished. | | search
CustomEvent<{value: string}> | Fired when a search is executed with Enter. | #### Methods | Method | Description | | --- | --- | | clear
() => void | Clears the search text and focuses the input. | | close
(reason?: string) => Promise<void> | Closes the view. | | focus
(options?: FocusOptions) => void | Focuses the search input. | | handleBack
() => Promise<void> | Handles a back request (the Android back gesture or button, which the view receives through its dialog): a full-screen view plays the predictive back motion, then the view closes with reason back. Call it for an in-app back control that should behave like the system back. | | render
() => TemplateResult<1> | Invoked on each update to perform rendering tasks. This method may return any value renderable by lit-html's ChildPart - typically a TemplateResult. Setting properties inside this method will *not* trigger the element to update. | | show
() => Promise<void> | Opens the view. | #### CSS parts | Part | Description | | --- | --- | | ::part(container) | The view's container. | | ::part(dialog) | The modal <dialog>. | | ::part(divider) | The divider of the divided style. | | ::part(header) | The header with the input. | | ::part(input) | The search input. | | ::part(results) | The role="listbox" results container. | #### CSS custom properties | Property | Description | | --- | --- | | --bar-container-height | Contained full-screen bar height. | | --bar-results-gap | Contained docked gap between the bar and results. | | --bar-shape | Contained bar shape. | | --contained-background-color | Contained full-screen background color. | | --contained-icon-label-gap | Space between the icon targets and the input. | | --contained-leading-margin | Contained full-screen bar leading margin. | | --contained-motion-duration | Contained expand and collapse duration. | | --contained-motion-spring | Contained expand and collapse easing. | | --contained-trailing-margin | Contained full-screen bar trailing margin. | | --container-color | Container color. | | --container-shape | Container shape. | | --content-fade-in-delay | Results fade in delay. | | --content-fade-in-duration | Results fade in duration. | | --content-fade-in-easing | Results fade in easing. | | --content-fade-out-duration | Results fade out duration. | | --content-fade-out-easing | Results fade out easing. | | --divided-collapse-motion-duration | Divided collapse duration. | | --divided-collapse-motion-spring | Divided collapse easing. | | --divided-expand-motion-duration | Divided expand duration. | | --divided-expand-motion-spring | Divided expand easing. | | --divider-color | Divided style divider color. | | --header-container-height | Header height. | | --header-input-text | Input typography. | | --header-input-text-axes | Input font variation settings. | | --header-input-text-color | Input text color. | | --header-input-text-tracking | Input letter spacing. | | --header-leading-icon-color | Back icon color. | | --header-supporting-text | Placeholder typography. | | --header-supporting-text-axes | Placeholder font variation settings. | | --header-supporting-text-color | Placeholder color. | | --header-supporting-text-tracking | Placeholder letter spacing. | | --header-trailing-icon-color | Trailing icon color. | | --icon-size | Icon size. | | --icon-target-size | Icon tap target size. | | --leading-space | Space before the leading icon. | | --max-height | Docked maximum height. | | --max-width | Docked maximum width. | | --min-height | Docked minimum height. | | --min-width | Docked minimum width. | | --results-shape | Contained docked results shape. | | --scrim-color | Docked scrim color. | | --trailing-space | Space after the trailing icon. |