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.