toc

Search

A search bar lets people enter a query and find matching results, with a search view that shows suggestions and results.

View as Markdown

<md-gb-search-bar placeholder="Search recipes">
  <md-gb-list-item static role="option">
    <md-gb-icon slot="leading">history</md-gb-icon>
    Mexican dishes
  </md-gb-list-item>
  <md-gb-list-item static role="option">
    <md-gb-icon slot="leading">history</md-gb-icon>
    Peanut sauce
  </md-gb-list-item>
  <md-gb-list-item static role="option">
    <md-gb-icon slot="leading">search</md-gb-icon>
    Pasta recipes
  </md-gb-list-item>
</md-gb-search-bar>

Install with shadcn/ui: npx shadcn@latest add https://material-web.dev/3.0/r/md-search.json (setup)

Usage guidelines

Link to “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 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 style puts a divider between the header and the results.
Make it prominent. A search app bar gives search an emphasized, global entry point.

This component is new in M3 Expressive.

Anatomy

Link to “Anatomy”

A search bar holds the leading and trailing elements; its default slot holds the suggestions or results shown in its search view.

mic

<md-gb-search-bar placeholder="Search recipes">
  <md-gb-icon-button slot="leading" aria-label="Open menu">
    <md-gb-icon>menu</md-gb-icon>
  </md-gb-icon-button>
  <md-gb-icon-button slot="trailing" aria-label="Voice search">
    <md-gb-icon>mic</md-gb-icon>
  </md-gb-icon-button>
  <md-gb-icon-button slot="view-trailing" aria-label="Voice search">
    <md-gb-icon>mic</md-gb-icon>
  </md-gb-icon-button>
  <md-gb-list-item static role="option">
    <md-gb-icon slot="leading">history</md-gb-icon>
    Mexican dishes
  </md-gb-list-item>
  <md-gb-list-item static role="option">
    <md-gb-icon slot="leading">search</md-gb-icon>
    Pasta recipes
  </md-gb-list-item>
</md-gb-search-bar>

Examples

Link to “Examples”

Trailing elements

Link to “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.

mic

<md-gb-search-bar placeholder="Search messages">
  <md-gb-icon-button slot="leading" aria-label="Open menu">
    <md-gb-icon>menu</md-gb-icon>
  </md-gb-icon-button>
  <md-gb-icon-button slot="trailing" aria-label="Voice search">
    <md-gb-icon>mic</md-gb-icon>
  </md-gb-icon-button>
</md-gb-search-bar>

Docked

Link to “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.

<md-gb-search-bar docked placeholder="Search recipes">
  <md-gb-list-item static role="option">
    <md-gb-icon slot="leading">search</md-gb-icon>
    Pancakes
  </md-gb-list-item>
  <md-gb-list-item static role="option">
    <md-gb-icon slot="leading">search</md-gb-icon>
    Pad thai
  </md-gb-list-item>
</md-gb-search-bar>

Divided

Link to “Divided”

Add divided to use the baseline style, with a divider between the view's header and its results.

<md-gb-search-bar divided placeholder="Search recipes">
  <md-gb-list-item static role="option">
    <md-gb-icon slot="leading">history</md-gb-icon>
    Plants
  </md-gb-list-item>
  <md-gb-list-item static role="option">
    <md-gb-icon slot="leading">search</md-gb-icon>
    Pasta recipes
  </md-gb-list-item>
</md-gb-search-bar>

Search app bar

Link to “Search app bar”

Put a search bar in the search slot of an app bar with variant="search". The app bar draws the container, so make the bar's container transparent.

account_circle

<md-gb-app-bar variant="search">
  <md-gb-search-bar slot="search" placeholder="Search recipes" style="--container-color: transparent"></md-gb-search-bar>
  <md-gb-icon-button slot="trailing" aria-label="Profile">
    <md-gb-icon>account_circle</md-gb-icon>
  </md-gb-icon-button>
</md-gb-app-bar>

Standalone search view

Link to “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.

HTML

<md-gb-icon-button id="open-search" aria-label="Search">
  <md-gb-icon>search</md-gb-icon>
</md-gb-icon-button>
<md-gb-search-view id="recipes" placeholder="Search recipes">
  <md-gb-list-item static role="option">
    <md-gb-icon slot="leading">history</md-gb-icon>
    Mexican dishes
  </md-gb-list-item>
  <md-gb-list-item static role="option">
    <md-gb-icon slot="leading">search</md-gb-icon>
    Pad thai
  </md-gb-list-item>
</md-gb-search-view>

document.querySelector('#open-search').addEventListener('click', () => {
  document.querySelector('#recipes').open = true;
});

Searching

Link to “Searching”

Set searching while you wait for results. The view shows a progress indicator and marks the results as busy.

HTML

<md-gb-search-bar placeholder="Search recipes"></md-gb-search-bar>

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

Link to “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.

Compatibility

Link to “Compatibility”

Material Design 3Spec checked76% tokens

154 of 297 buildable spec units are tested, 13 are excluded with a written reason and 0 are uncovered (the target is 0). 60 of 79 token declarations match the spec (76%), and 19 have no spec token.

search on m3.material.io (opens in a new tab) How compliance is measured

BaselineWidely availableChrome 124Edge 124Firefox 125Safari 17.4

The component’s own CSS and JavaScript rely only on web platform features that are Baseline widely available: it works in Chrome 124, Edge 124, Firefox 125, Safari 17.4 and later.

Newer features it uses where the browser has them (progressive enhancements):

Cursor styles (opens in a new tab) Limited availability degrades safely where it is missing
overscroll-behavior (opens in a new tab) Limited availability degrades safely where it is missing
scrollbar-color (opens in a new tab) Newly available degrades safely where it is missing
scrollbar-gutter (opens in a new tab) Newly available degrades safely where it is missing
scrollbar-width (opens in a new tab) Newly available degrades safely where it is missing

Browser support Learn more about Baseline (opens in a new tab)

WAI-ARIAaxe and ARIA 1.3 passButtonCombobox

Roles the component renders: button (opens in a new tab), combobox (opens in a new tab), dialog (opens in a new tab), listbox (opens in a new tab), option (opens in a new tab), status (opens in a new tab), textbox (opens in a new tab).

Follows the WAI-ARIA Authoring Practices: Button (opens in a new tab), Combobox (opens in a new tab), Dialog (Modal) (opens in a new tab), Listbox (opens in a new tab).

3 rendered states run through axe-core and the WAI-ARIA 1.3 role and attribute rules in a real browser, with no known gaps.

WAI-ARIA 1.3 (opens in a new tab) ARIA Authoring Practices (opens in a new tab) Accessibility

Lighthouse98 · 100 · 100 · 100

Performance
Accessibility
Best practices
SEO

Audits under 90:

Eliminate render-blocking resources
Minify JavaScript
Reduce unused CSS
Enable text compression
Network dependency tree
Render blocking requests

Lighthouse 12.8.2 (desktop, 2026-11-08) on the component alone: its first example on a page of its own, without this site's shell. The modules are the development build (not bundled or minified), so the performance score is indicative.

Open the test page About Lighthouse (opens in a new tab)

API reference

Link to “API reference”

<md-gb-search-bar>

Link to “<md-gb-search-bar>”

A Material Design search bar.

Properties

Link to “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

Link to “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

Link to “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

Link to “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

Link to “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

Link to “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>

Link to “<md-gb-search-view>”

Focused search: suggestions or results opened from a search bar.

Properties

Link to “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

Link to “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

Link to “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

Link to “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

Link to “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

Link to “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.

Search

Usage guidelines

Anatomy

Examples

Trailing elements

Docked

Divided

Search app bar

Standalone search view

Searching

Accessibility

Compatibility

API reference

<md-gb-search-bar>

Properties

Slots

Events

Methods

CSS parts

CSS custom properties

<md-gb-search-view>

Properties

Slots

Events

Methods

CSS parts

CSS custom properties

Download & copy

Download

Copy

Customize theme