Autocomplete

Overview

Autocomplete provides options in a dropdown list as user types in an input box by showing result from an API call or a static list.

Installation

npm install @patternfly/pfe-autocomplete

Usage

<pfe-autocomplete>
  <input placeholder="Enter your search term" />
</pfe-autocomplete>

aria-label

This is an optional attribute string that you can provide on the input tag in the light DOM of pfe-autocomplete. The aria-label attribute will default to "Search".

<pfe-autocomplete>
  <input placeholder="Search" aria-label="Buscar" />
</pfe-autocomplete>

Setup

autocompleteRequest

autocompleteRequest is a property that is assigned a function. When user types, component calls this function.

It is called inside component but we define it outside component. First param is the typed phrase by user and second param is a callback function to send api response back to the component.

In the function, we add loading attribute then send api call. When result is ready, we remove loading attribute and pass the result to web component by calling callback function. Here is an example:

// autocomplete call
searchAutocomplete.autocompleteRequest = function (params, callback) {
  searchAutocomplete.loading = true;
  const url = new URL('http://openlibrary.org/search.json');
        url.searchParams.append('title', params.query);
  fetch(url.toString())
    .then(x => x.json())
    .then(({ docs }) => docs.map(x => x.title))
    .then(callback)
    .then(() => searchAutocomplete.loading = false);
};

Slots

Default Slot

Users must slot a single <input> element in to <pfe-autocomplete>

Attributes

color-palette

Sets color palette, which affects the element's styles as well as descendants' color theme. Overrides parent color context. Your theme will influence these colors so check there first if you are seeing inconsistencies. See Color for default values

DOM Property

colorPalette

Type

ColorPalette | undefined

Default

unknown

on

Sets color theme based on parent context

DOM Property

on

Type

ColorTheme

Default

'light'

init-value

Set this attribute when you want to set a value in input box when web component is added to page.

DOM Property

initValue

Type

string

Default

''

loading

If you add this attribute on element, a loading icon is added in input box. Add this attribute before the autocomplete API call and remove it when the response is ready.

DOM Property

loading

Type

boolean

Default

false

disabled

Add this attribute to disable the element. By adding this attribute input box and buttons become disabled.

DOM Property

disabled

Type

boolean

Default

false

debounce

Users may type very fast. We allow to input box value changes trigger the autocomplete API call only once per debounce period. This attribute is optional. By default, it is set t0 300ms.

DOM Property

debounce

Type

number

Default

300

selected-value

By observing selected-value attribute you can detect autocomplete selected value.

DOM Property

selectedValue

Type

string | undefined

Default

unknown

button-text

Set when you want to have a textual search button to the right of the input field. The text in the button will contain the value you pass to the attribute. If an empty string (button-text="") or no string (button-text) is provided, the text will default to "Search".

DOM Property

buttonText

Type

string | undefined

Default

unknown

announce-template

Optional translated string you provide for the ARIA Live Region which will politely announce that the number of options the user can select from as the autocomplete displays options.

The default template is "There are ${numOptions} suggestions. Use the up and down arrows to browse." ${numOptions} will be dynamically replaced with the number of options that are shown.

DOM Property

announceTemplate

Type

string

Default

'There are ${numOptions} suggestions. Use the up and down arrows to browse.'

DOM Properties

data

The list of search dropdown items

Type

string[]

Default

[]

autocompleteRequest

Optional callback to asynchronously return search items

Type

AutocompleteRequestFunction | undefined

Default

unknown

Methods

clear()

Clear the search dropdown

search()

Perform the search

Events

show

When the search dropdown is shown

Event Type:

AutocompleteShowEvent

clear

Fires when a user clears the input field using the clear button.

Event Type:

AutocompleteClearEvent

search

Fires when a user performs search. By listening to this event you can get selected phrase by getting event.value.

Event Type:

AutocompleteSearchEvent

select

Fires when a user selects an option from the dropdown list.

Event Type:

AutocompleteSelectEvent

Events on pfe-search-droplist

select

When an option is selected.

Event Type:

DroplistSelectEvent

CSS Custom Properties

CSS Shadow Parts

container

The input wrapper

icon

The loading icon

clear-button

The clear button

search-button

The search button

droplist

The search droplist

text-search-button

The textual search button Shown when [button-text] attr provided