PatternFly Elements - Home PatternFly Elements v2 prerelease v1

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.'

Deprecated Attributes

is-disabled
Note: is-disabled is deprecated.
DOM Property
isDisabled
Type
boolean | undefined
Default
unknown
aria-announce-template
Note: aria-announce-template is deprecated.
DOM Property
ariaAnnounceTemplate
Type
unknown
Default
unknown

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

Deprecated DOM Properties

color
Note: color is deprecated.

use color-palette

Type
ColorPalette | 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

Deprecated Events

pfe-autocomplete:options-shown

When the search dropdown is shown

Note: pfe-autocomplete:options-shown is deprecated.

Use show

Event Type:
Event
pfe-autocomplete:option-cleared

When the search dropdown is cleared

detail: {
searchValue: ''
}

Note: pfe-autocomplete:option-cleared is deprecated.

Use clear

Event Type:
CustomEvent<{ searchValue: '' }>
pfe-autocomplete:search-event

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

Note: pfe-autocomplete:search-event is deprecated.

Use search

Event Type:
CustomEvent<{ searchValue: string }>
pfe-autocomplete:option-selected

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

detail: {
optionValue: String
}

Note: pfe-autocomplete:option-selected is deprecated.

Use select

Event Type:
CustomEvent<{ optionValue: '' }>

Events on pfe-search-droplist

select

When an option is selected.

Event Type:
DroplistSelectEvent

Deprecated Events on pfe-search-droplist

pfe-autocomplete:option-selected
Note: pfe-autocomplete:option-selected is deprecated.

Use select

Event Type:
CustomEvent<{ optionValue: string }>

CSS Custom Properties

None

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