PrimeFaces Users Guide
3.4 AutoComplete
AutoComplete provides live suggestions while an input is being typed.
Info
Tag
autoComplete
Component Class
org.primefaces.component.autocomplete.AutoComplete
Component Type
org.primefaces.component.AutoComplete
Component Family
org.primefaces.component
Renderer Type
org.primefaces.component.AutoCompleteRenderer
Renderer Class
org.primefaces.component.autocomplete.AutoCompleteRenderer
Attributes
Name
Default
Type
Description
id
null
String
Unique identifier of the component.
rendered
TRUE
Boolean
Boolean value to specify the rendering of the
component.
binding
null
Object
An el expression that maps to a server side
UIComponent instance in a backing bean.
value
null
Object
Value of the component than can be either an
EL expression of a literal text.
converter
null
Converter/
String
An el expression or a literal text that defines a
converter for the component. When its an EL
expression, its resolved to a converter instance.
In case its a static text, it must refer to a
converter id.
24
PrimeFaces Users Guide
Name
Default
Type
Description
immediate
FALSE
Boolean
When set true, process validations logic is
executed at apply request values phase for this
component.
required
FALSE
Boolean
Marks component as required.
validator
null
MethodExpr
A method expression that refers to a method
validationg the input.
valueChangeListener
null
MethodExpr
A method expression that refers to a method for
handling a valuchangeevent.
requiredMessage
null
String
Message to be displayed when required field
validation fails.
converterMessage
null
String
Message to be displayed when conversion fails.
validatorMessage
null
String
Message to be displayed when validation fails.
widgetVar
null
String
Name of the client side widget.
completeMethod
null
MethodExpr
Method providing suggestions.
var
null
String
Name of the iterator used in pojo based
suggestion.
itemLabel
null
String
Label of the item.
itemValue
null
String
Value of the item.
maxResults
unlimited
Integer
Maximum number of results to be displayed.
minQueryLength
Integer
Number of characters to be typed before starting
to query.
queryDelay
300
Integer
Delay to wait in milliseconds before sending
each query to the server.
forceSelection
FALSE
Boolean
When enabled, autoComplete only accepts input
from the selection list.
onstart
null
String
Client side callback to execute before ajax
request to load suggestions begins.
oncomplete
null
String
Client side callback to execute after ajax request
to load suggestions completes.
global
TRUE
Boolean
Defines whether to trigger ajaxStatus or not.
scrollHeight
null
Integer
Defines the height of the items viewport.
effect
null
String
Effect to use when showing/hiding suggestions.
effectDuration
400
Integer
Duration of effect in milliseconds.
dropdown
FALSE
Boolean
Enables dropdown mode when set true.
panelStyle
null
String
Inline style of the items container element.
25
PrimeFaces Users Guide
Name
Default
Type
Description
panelStyleClass
null
String
Style class of the items container element.
multiple
null
Boolean
When true, enables multiple selection.
process
null
String
Component(s) to process on query request.
accesskey
null
String
Access key that when pressed transfers focus to
the input element.
alt
null
String
Alternate textual description of the input field.
autocomplete
null
String
Controls browser autocomplete behavior.
dir
null
String
Direction indication for text that does not inherit
directionality. Valid values are LTR and RTL.
disabled
FALSE
Boolean
Disables input field
label
null
String
A localized user presentable name.
lang
null
String
Code describing the language used in the
generated markup for this component.
maxlength
null
Integer
Maximum number of characters that may be
entered in this field.
onblur
null
String
Client side callback to execute when input
element loses focus.
onchange
null
String
Client side callback to execute when input
element loses focus and its value has been
modified since gaining focus.
onclick
null
String
Client side callback to execute when input
element is clicked.
ondblclick
null
String
Client side callback to execute when input
element is double clicked.
onfocus
null
String
Client side callback to execute when input
element receives focus.
onkeydown
null
String
Client side callback to execute when a key is
pressed down over input element.
onkeypress
null
String
Client side callback to execute when a key is
pressed and released over input element.
onkeyup
null
String
Client side callback to execute when a key is
released over input element.
onmousedown
null
String
Client side callback to execute when a pointer
button is pressed down over input element
onmousemove
null
String
Client side callback to execute when a pointer
button is moved within input element.
onmouseout
null
String
Client side callback to execute when a pointer
button is moved away from input element.
26
PrimeFaces Users Guide
Name
Default
Type
Description
onmouseover
null
String
Client side callback to execute when a pointer
button is moved onto input element.
onmouseup
null
String
Client side callback to execute when a pointer
button is released over input element.
onselect
null
String
Client side callback to execute when text within
input element is selected by user.
readonly
FALSE
Boolean
Flag indicating that this component will prevent
changes by the user.
size
null
Integer
Number of characters used to determine the
width of the input element.
style
null
String
Inline style of the input element.
styleClass
null
String
Style class of the input element.
tabindex
null
Integer
Position of the input element in the tabbing
order.
title
null
String
Advisory tooltip informaton.
Getting Started with AutoComplete
Suggestions are loaded by calling a server side completeMethod that takes a single string parameter
which is the text entered. Since autoComplete is an input component, it requires a value as usual.
<p:autoComplete value="#{bean.text}" completeMethod="#{bean.complete}" />
public class Bean {
private String text;
//getter setter
public List<String> complete(String query) {
List<String> results = new ArrayList<String>();
for (int i = 0; i < 10; i++)
results.add(query + i);
return results;
}
27
PrimeFaces Users Guide
Pojo Support
Most of the time, instead of simple strings you would need work with your domain objects,
autoComplete supports this common use case with the use of a converter and data iterator.
Following example loads a list of players, itemLabel is the label displayed as a suggestion and
itemValue is the submitted value. Note that when working with pojos, you need to plug-in your own
converter.
<p:autoComplete value="#{playerBean.selectedPlayer}"
completeMethod="#{playerBean.completePlayer}"
var="player"
itemLabel="#{player.name}"
itemValue="#{player}"
converter="playerConverter"/>
public class PlayerBean {
private Player selectedPlayer;
public
}
public
}
Player getSelectedPlayer() {
return selectedPlayer;
void setSelectedPlayer(Player selectedPlayer) {
this.selectedPlayer = selectedPlayer;
public List<Player> complete(String query) {
List<Player> players = readPlayersFromDatasource(query);
return players;
}
public class Player {
}
private String name;
//getter setter
Limiting the Results
Number of results shown can be limited, by default there is no limit.
<p:autoComplete value="#{bean.text}"
completeMethod="#{bean.complete}"
maxResults="5" />
28
PrimeFaces Users Guide
Minimum Query Length
By default queries are sent to the server and completeMethod is called as soon as users starts typing
at the input text. This behavior is tuned using the minQueryLength attribute.
<p:autoComplete value="#{bean.text}" completeMethod="#{bean.complete}"
minQueryLength="3" />
With this setting, suggestions will start when user types the 3rd character at the input field.
Query Delay
AutoComplete is optimized using queryDelay option, by default autoComplete waits for 300
milliseconds to query a suggestion request, if youd like to tune the load balance, give a longer
value. Following autoComplete waits for 1 second after user types an input.
<p:autoComplete value="#{bean.text}" completeMethod="#{bean.complete}"
queryDelay="1000" />
Custom Content
AutoComplete can display custom content by nesting columns.
<p:autoComplete value="#{autoCompleteBean.selectedPlayer}"
completeMethod="#{autoCompleteBean.completePlayer}"
var="p" itemValue="#{p}" converter="player">
<p:column>
<p:graphicImage value="/images/barca/#{p.photo}" width="40" height="50"/>
</p:column>
<p:column>
#{p.name} - #{p.number}
</p:column>
</p:autoComplete>
Dropdown Mode
When dropdown mode is enabled, a dropdown button is displayed next to the input field, clicking
this button will do a search with an empty query, a regular completeMethod implementation should
load all available items as a response.
<p:autoComplete value="#{bean.text}" completeMethod="#{bean.complete}"
dropdown="true" />
29
PrimeFaces Users Guide
Multiple Selection
AutoComplete supports multiple selection as well, to use this feature set multiple option to true and
define a list as your backend model. Following example demonstrates multiple selection with
custom content support.
<p:autoComplete id="advanced" value="#{autoCompleteBean.selectedPlayers}"
completeMethod="#{autoCompleteBean.completePlayer}"
var="p" itemLabel="#{p.name}" itemValue="#{p}" converter="player"
multiple="true">
<p:column style="width:20%;text-align:center">
<p:graphicImage value="/images/barca/#{p.photo}"/>
</p:column>
<p:column style="width:80%">
#{p.name} - #{p.number}
</p:column>
</p:autoComplete>
public class AutoCompleteBean {
private List<Player> selectedPlayers;
//...
Ajax Behavior Events
Instead of waiting for user to submit the form manually to process the selected item, you can enable
instant ajax selection by using the itemSelect ajax behavior. Example below demonstrates how to
display a message about the selected item instantly.
<p:autoComplete value="#{bean.text}" completeMethod="#{bean.complete}">
<p:ajax event="itemSelect" listener="bean.handleSelect" update="msg" />
</p:autoComplete>
<p:messages id=msg />
30
PrimeFaces Users Guide
public class Bean {
public void handleSelect(SelectEvent event) {
Object item = event.getObject();
FacesMessage msg = new FacesMessage("Selected", "Item:" + item);
}
...
Your listener(if defined) will be invoked with an org.primefaces.event.Select instance that contains
a reference to the selected item. Note that autoComplete also supports events inherited from regular
input text such as blur, focus, mouseover in addition to itemSelect. Similarly, itemUnselect event is
provided for multiple autocomplete when an item is removed by clicking the remove icon. In this
case org.primefaces.event.Unselect instance is passed to a listener if defined.
ItemTip
Itemtip is an advanced built-in tooltip when mouse is over on suggested items. Content of the
tooltip is defined via the itemtip facet.
<p:autoComplete value="#{autoCompleteBean.selectedPlayer1}" id="basicPojo"
completeMethod="#{autoCompleteBean.completePlayer}"
var="p" itemLabel="#{p.name}" itemValue="#{p}" converter="player">
<f:facet name="itemtip">
<h:panelGrid columns="2" cellpadding="5">
<f:facet name="header">
<p:graphicImage value="/images/barca/#{p.photo}" />
</f:facet>
<h:outputText value="Name: " />
<h:outputText id="modelNo" value="#{p.name}" />
<h:outputText value="Number " />
<h:outputText id="year" value="#{p.number}" />
<h:outputText value="Position " />
<h:outputText value="#{p.position}"/>
</h:panelGrid>
</f:facet>
</p:autoComplete>
31
PrimeFaces Users Guide
Client Side Callbacks
onstart and oncomplete are used to execute custom javascript before and after an ajax request to
load suggestions.
<p:autoComplete value="#{bean.text}" completeMethod="#{bean.complete}"
onstart="handleStart(request)" oncomplete="handleComplete(response)" />
onstart callback gets a request parameter and oncomplete gets a response parameter, these
parameters contain useful information. For example request is the query string and response is the
xhr request sent under the hood.
Client Side API
Widget: PrimeFaces.widget.AutoComplete
Method
Params
Return Type
value: keyword for search
void
Initiates a search with given value
close()
void
Hides suggested items menu
disable()
void
Disables the input field
enable()
void
Enables the input field
deactivate()
void
Deactivates search behavior
activate()
void
Activates search behavior
search(value)
Description
Skinning
Following is the list of structural style classes;
Class
Applies
.ui-autocomplete
Container element.
.ui-autocomplete-input
Input field.
.ui-autocomplete-panel
Container of suggestions list.
.ui-autocomplete-items
List of items
.ui-autocomplete-item
Each item in the list.
.ui-autocomplete-query
Highlighted part in suggestions.
As skinning style classes are global, see the main theming section for more information.
32
PrimeFaces Users Guide
Tips
Do not forget to use a converter when working with pojos.
Enable forceSelection if youd like to accept values only from suggested list.
Increase query delay to avoid unnecessary load to server as a result of user typing fast.
33
