Autocomplete is a field component that allows users to search and select from a list of options.

Vertical Layout

Chrome Firefox Internet Explorer Safari
Chrome Firefox Internet Explorer Safari Required Information
Chrome Firefox Internet Explorer Safari Error Message
Show Markup

                      

Aligned Layout

Chrome Firefox Internet Explorer Safari
Chrome Firefox Internet Explorer Safari Required Information
Chrome Firefox Internet Explorer Safari Error Message
Show Markup

            

Remote Suggestions

Listen to the coral-autocomplete:showsuggestions event and call event.preventDefault() to stop the default behavior of searching items for suggestions. Then, use event.detail.value to request suggestions from the server. Once you have suggestions, pass an array of suggestion objects to autocomplete.addSuggestions() to show suggestions. Listen to the coral-autocomplete:hidesuggestions event and abort any requests you've made to avoid showing suggestions when the user hidden them.

Show Markup

                      
                              

Coral.Autocomplete API

Constructor

JavaScript:

new Coral.Autocomplete() or document.createElement('coral-autocomplete')

HTML Tag:

<coral-autocomplete>

Extends

Sub-components

Static Properties

Coral.Autocomplete.match {String}

Enumeration of match values.

Properties:

Name Type Value Description
STARTSWITH String startswith Include only matches that start with the user provided value.
CONTAINS String contains Include only matches that contain the user provided value.

Instance Properties

instance.delay {Number}

Reflected
Amount of time, in milliseconds, to wait after typing a character before the suggestion is shown.
Default Value:
  • 200
HTML Attribute:
  • delay

instance.disabled {Boolean}

Reflected
Whether this field is disabled or not.
Inherited From:
Default Value:
  • false
HTML Attribute:
  • disabled

instance.icon {String}

Reflected
The icon of the autocomplete.
Default Value:
  • ""
HTML Attribute:
  • icon

instance.invalid {Boolean}

Reflected
Whether the current value of this field is invalid or not.
Inherited From:
Default Value:
  • false
HTML Attribute:
  • invalid

instance.items {Coral.Collection}

Readonly
The item collection. See Coral.Collection for more details.

instance.labelledBy {String}

Reference to a space delimited set of ids for the HTML elements that provide a label for the formField. Implementers should override this method to ensure that the appropriate descendant elements are labelled using the aria-labelledby attribute. This will ensure that the component is properly identified for accessibility purposes. It reflects the aria-labelledby attribute to the DOM.
Inherited From:
Default Value:
  • null
HTML Attribute:
  • labelledby

instance.loading {Boolean}

Indicates that the component is currently loading remote data. This will set the wait indicator inside the list.
Default Value:
  • false
HTML Attribute:
  • loading

instance.match {String}

The match mode.
Default Value:
  • Coral.Autocomplete.match.CONTAINS
HTML Attribute:
  • match

instance.multiple {Boolean}

Reflected
Indicates if the autocomplete is a single or multiple mode. In multiple mode, the user can select multiple values.
Default Value:
  • false
HTML Attribute:
  • multiple

instance.name {String}

Reflected
Name used to submit the data in a form.
Inherited From:
Default Value:
  • ""
HTML Attribute:
  • name

instance.placeholder {String}

Reflected
A hint to the user of what can be entered.
Default Value:
  • ""
HTML Attribute:
  • placeholder

instance.readOnly {Boolean}

Reflected
Whether this field is readOnly or not. Indicating that the user cannot modify the value of the control. This is ignored for checkbox, radio or fileupload.
Inherited From:
Default Value:
  • false
HTML Attribute:
  • readonly

instance.required {Boolean}

Reflected
Whether this field is required or not.
Inherited From:
Default Value:
  • false
HTML Attribute:
  • required

instance.value {String}

The current value, as submitted during form submission. When Coral.Autocomplete#multiple is true, the first selected value will be returned.
Default Value:
  • ""
HTML Attribute:
  • value

instance.values {Array.<String>}

The current values, as submitted during form submission. When Coral.Autocomplete#multiple is false, this will be an array of length 1.

Methods

instance.addSuggestions

Add the provided list of suggestions and clear loading status.
Parameters:
Name Type Description
suggestions Array.<Coral.Autocomplete~suggestion> The list of suggestions to show.
clear Boolean If true, existing suggestions will be cleared.

instance.clear

Clears the current selected value or items.

instance.clearSuggestions

Clear the list of suggestions.

instance.get

Get the value of a property.
Parameters:
Name Type Description
property String The name of the property to fetch the value of.
Returns:
Property value. {*}
Inherited From:

instance.hideSuggestions

Hides the suggestion UI.

instance.off

Remove an event listener.
Parameters:
Name Type Optional Description
eventName String No
The event name to stop listening for.
selector String Yes
The selector that was used for event delegation.
func function No
The function that was passed to on().
useCapture Boolean Yes
Only remove listeners with useCapture set to the value passed in.
Returns:
this, chainable. {Coral.Component}
Inherited From:

instance.on

Add an event listener.
Parameters:
Name Type Optional Default Description
eventName String No
The event name to listen for.
selector String Yes
The selector to use for event delegation.
func function No
The function that will be called when the event is triggered.
useCapture Boolean Yes
false Whether or not to listen during the capturing or bubbling phase.
Returns:
this, chainable. {Coral.Component}
Inherited From:

instance.remove

Non-destructively remove this element. It can be re-added by simply appending it to the document again. It will be garbage collected if there are no more references to it. This is different from using jQuery's remove(), which is destructive in that it removes data and listeners.
Inherited From:

instance.showSuggestions

Shows the suggestion UI.

instance.trigger

Trigger an event.
Parameters:
Name Type Optional Default Description
eventName String No
The event name to trigger.
props Object Yes
Additional properties to make available to handlers as event.detail.
bubbles Boolean Yes
true Set to false to prevent the event from bubbling.
cancelable Boolean Yes
true Set to false to prevent the event from being cancelable.
Returns:
CustomEvent object {CustomEvent}
Inherited From:

Type Definitions

suggestion

A suggestion object.

Properties:

Name Type Argument Default Description
value String The form submission value to use when this suggestion is selected.
content String <optional>
value The content to disable in the suggestion dropdown.

Events

change

Triggered when the value has changed. This event is only triggered by user interaction.
Callback Parameters:
Name Type Description
event Object Event object.
Inherited From:

coral-autocomplete:showsuggestions

Triggered before suggestions are determined and displayed.
Callback Parameters:
Name Type Description
event Object

Event object.

Name Type Description
event.detail.value HTMLElement The user-provided input value.
event.detail.start HTMLElement The count of existing suggestions, the index from which new suggestions should start at.
event.preventDefault function When called, prevent search for suggestions in existing items and show a loading indicator. Suggestions can be manually added by calling Coral.Autocomplete#showSuggestions.

coral-component:attached

Triggered when the component is attached to the DOM.
Callback Parameters:
Name Type Description
event Object Event object.
Inherited From:

coral-component:detached

Triggered when the component is detached to the DOM.
Callback Parameters:
Name Type Description
event Object Event object.
Inherited From:

coral-component:ready

Triggerred when the component has been upgraded and is ready for use.
Callback Parameters:
Name Type Description
event Object Event object.
Inherited From:

Coral.Autocomplete.Item API

Constructor

JavaScript:

new Coral.Autocomplete.Item() or document.createElement('coral-autocomplete-item')

HTML Tag:

<coral-autocomplete-item>

Extends

Instance Properties

instance.content {HTMLElement}

The content zone element of the item.

instance.selected {Boolean}

Reflected
Whether this item is selected.
Default Value:
  • false
HTML Attribute:
  • selected

instance.value {String}

Reflected
Value of the item. textContent is used if not provided.
Default Value:
  • ""
HTML Attribute:
  • value

Methods

instance.get

Get the value of a property.
Parameters:
Name Type Description
property String The name of the property to fetch the value of.
Returns:
Property value. {*}
Inherited From:

instance.off

Remove an event listener.
Parameters:
Name Type Optional Description
eventName String No
The event name to stop listening for.
selector String Yes
The selector that was used for event delegation.
func function No
The function that was passed to on().
useCapture Boolean Yes
Only remove listeners with useCapture set to the value passed in.
Returns:
this, chainable. {Coral.Component}
Inherited From:

instance.on

Add an event listener.
Parameters:
Name Type Optional Default Description
eventName String No
The event name to listen for.
selector String Yes
The selector to use for event delegation.
func function No
The function that will be called when the event is triggered.
useCapture Boolean Yes
false Whether or not to listen during the capturing or bubbling phase.
Returns:
this, chainable. {Coral.Component}
Inherited From:

instance.remove

Non-destructively remove this element. It can be re-added by simply appending it to the document again. It will be garbage collected if there are no more references to it. This is different from using jQuery's remove(), which is destructive in that it removes data and listeners.
Inherited From:

instance.trigger

Trigger an event.
Parameters:
Name Type Optional Default Description
eventName String No
The event name to trigger.
props Object Yes
Additional properties to make available to handlers as event.detail.
bubbles Boolean Yes
true Set to false to prevent the event from bubbling.
cancelable Boolean Yes
true Set to false to prevent the event from being cancelable.
Returns:
CustomEvent object {CustomEvent}
Inherited From:

Events

coral-component:attached

Triggered when the component is attached to the DOM.
Callback Parameters:
Name Type Description
event Object Event object.
Inherited From:

coral-component:detached

Triggered when the component is detached to the DOM.
Callback Parameters:
Name Type Description
event Object Event object.
Inherited From:

coral-component:ready

Triggerred when the component has been upgraded and is ready for use.
Callback Parameters:
Name Type Description
event Object Event object.
Inherited From: