@exmg/exmg-searchbar

exmg-searchbar

A customizable search bar element.

This search bar uses mwc-textfield for the input element. More information about styling and the input element itself can be found on the link below: https://github.com/material-components/material-components-web-components/tree/master/packages/textfield

Usage

Import this element to your project with npm i @exmg/exmg-searchbar.

Then add the snippet below into your code.

<exmg-searchbar></exmg-searchbar>

Default Filtering

ExmgSearchBar has it's own filtering methods in it which you can also override. To achieve default filtering, take the example of html code below:

<exmg-searchbar .data="${dataArray}" .filterKeys="${filterKeys}" suggestion-label-key="url"> </exmg-searchbar>

When you pass the data array into data property along with filterKeys, exmg-search bar automatically filters data and shows suggestions.

filterKeys property has to contain specific key names from the type of each item in data.

For example; if you have [{username:"exmachina",name: "Ex Machina"},{username:"livery",name:"Livery"}] as the data array, you can pass ['username'] to filter out username values of data. Or pass ['username', 'name'] to filter out values of both keys.

To determine which value of items passed into data should be shown as the label of each suggestion, use suggestion-label-key just like filterKeys but the only difference is, it accepts a single key as a simple string, not an array.

Custom Suggestions and Filtering

By extending ExmgSearchBar, you can override any of three functions of your selection. These functions are:

• filter(data: any[], filterKeys: string[], query: string): ExmgSearchSuggestion[]: TemplateResult
• renderSuggestions(suggestions: ExmgSearchSuggestion[])
• renderSuggestionsLoading(): TemplateResult

filter expects array of ExmgSearchSuggestion objects. By implementing your own filtering method, you might not need suggestion-label-key since you can place any string value into text property of ExmgSearchSuggestion.

Please check ExmgSearchBar class in order to see how these three functions are working. After that you can extend ExmgSearchBar class and override those functions to create your fancy filtering methods or suggestions.

Showing Suggestions Manually

If you are handling filtering logic manually on the parent, you can follow this way to show suggestions manually. To show suggestons, pass the suggestion data to suggestions property of exmg-searchbar. It accepts array of ExmgSearchSuggestion type of elements into suggestions.

Follow this document for available properties, events, methods and styling.

Styling

Variable	Default	Description
--exmg-searchbar-error-color	#b00020	Error color of search bar
--exmg-searchbar-hint-color	rgba(0, 0, 0, 0.6)	Hint text color of search bar
--exmg-searchbar-primary-color	#0071dc	Primary theme color of search bar
--exmg-searchbar-text-color	rgba(0, 0, 0, 0.87)	Text color of search bar
--exmg-searchbar-suggestions-spinner-color	#0071dc	Suggestions loading indicator color
--exmg-searchbar-suggestions-spinner-width	3px	Suggestions loading indicator spinner width
--exmg-searchbar-suggestions-max-visible-suggestions	5	Max visible suggestions before showing scrollbar
--exmg-searchbar-suggestions-min-height	40px	Suggestion item row height
--exmg-searchbar-suggestions-text-color	rgba(0, 0, 0, 0.6)	Suggestion item text color
--exmg-searchbar-suggestions-background-color	#ffffff	Suggestions list background color
--exmg-searchbar-suggestions-z-index	1	z-index of suggestions list
--exmg-searchbar-width	100%	Width of search bar

Properties

Name	Type	Default	Description
filterKeys	string[]	undefined	Set of which keys of data should be checked to filter data by default.
data	any[]	undefined	The data in search bar to filter.
keepFocus	boolean	false	If true, keeps focus on search bar after query-submit is fired
keepSuggestionsOnSelect	boolean	false	Option to whether keep suggestions visible or not on suggestion selection
submitKeys	string[]	['ENTER']	Determines which keys should trigger submitting search query
notifyOnQueryChange	boolean	true	If true, dispatches query-change event with the current query on every change of search input.
searchQuery	string	''	Current query of search bar
suggestionLabelKey	string	undefined	Defines which property of each data item should be placed into suggestions' labels.
submitOnKeyPress	boolean	true	If true, dispatches query-submit event with the current query upon receiving key press event with specific keys passed to keys string array
suggestions	ExmgSearchSuggestion[]	[]	List of suggestions to be passed into and displayed
suggestionsLoading	boolean	false	If true and there are no suggestions passed to element, a loading indicator should be shownbar

Events

@query-change

Fired on query change.

Payload: {value: string}

@query-submit

Fired on query submit.

Payload: {value: string}

@suggestion-select

Fired on suggestion selection.

This event is also fired when there is only one suggestion and user submits query.

Payload: {value: any, index: number}

Methods

clearSuggestions()

Clears suggestions.

hideSuggestionsLoading()

Hides the loading indicator.

search()

Fires query-submit event with passed query into search bar.

setQuery(query: string)

Sets query.

setSuggestions(suggestions: ExmgSearchSuggestion[])

Sets suggestions.

showSuggestionsLoading()

Shows the loading indicator if there are no suggestions available.