The search component allows the user to filter data based on a query. There are two variants: a basic component for simple filtering, and a "search and find" variant which has buttons to browse the results, displays which result is currently highlighted ("x of y results") and provides a "jump to result" link for keyboard users.

The component does not handle the data to filter. It simply gives you the text typed by the user through the value property, which is typically retrieved via the "input" event (e.g. inside the callback function). Use the num-results property to pass the number of results back to the component.

In the "search and find variant", the user browses the results using the component's arrow buttons, which emit the event wmSearchBrowseResults. In the callback function, use event.detail.position to retrieve the position of the result in the list, and set the highlighted-id and highlighted-name properties to the current search result (for accessibility reasons).

Properties Examples Events Accessibility Notes

* Required property

basic | find
Variant of the component. Defaults to basic
placeholder *
The placeholder text displayed in the input when it is empty.
label *
The component's label (for accessibility). It may be the same as the placeholder.
num-results *
The number of results yielded by the user's query.
The input's value (text typed by the user), for access by the app.
highlighted-id *
Required for the search and find variant only. id of the item currently hightlighted.
highlighted-name *
Required for the search and find variant only. Text of the item currently highlighted.

Usage in HTML

Edit the code below to see changes reflected in the example above.

Javascript Sample

Example code for functionality.

Usage in Elm

Code generated from HTML.

Emitted when the buttons in the search-and-find variant are pressed. The event detail contains a 'position' key representing the order of the item currently highlighted. Replaces the deprecated wmBrowseSearchResults.
Emitted on blur when Search's value changes.
Emitted when a user types in the input field.


Screen readers announce the number of results

When using the "search and find" version, if there are results and the user is tabbing, the component displays a link to jump to the search result (similar to a "skip navigation" link).

The component doesn't handle the results list; the filtering needs to be implemented, using the information exposed by the component through properties and events. Similarly, in the "search and find" variant, the highlighting needs to be handled outside of the component (for the same reason: the component doesn't have access to the results list).

The component emits an event on "input", not on "change". Make sure the callback function is hooked to the proper event.

In a compound component like Select or Action Menu, child components are rendered in the parent's slot element, part of its shadow DOM tree. Slots essentially serve as a placeholder for markup that you the developer define in the light DOM tree, like <wm-menuitem>, <wm-option>, text content, or other child elements.

The browser distributes the child elements defined in the light DOM into the shadow DOM of the parent. The result is a flattened DOM tree—a merger of the the light DOM and the shadow DOM. This flattened tree is what you see in DevTools and what is rendered on the page.

With the standard implementation of the component, dynamically updating the child items will throw an error. Elm's efficient diffing of the DOM will register that only the child items have changed and try to update them, but the component has already been composed.

Rendering the component in a Keyed node and giving it a dynamic id will cause the entire component, rather than just the child items, to render anew, avoiding the error.