Home > Guides > Tag Developers Guide > Struts Tags > Tag Reference > UI Tag Reference > autocompleter

To use this tag:

  • Add: <%@ taglib prefix="sx" uri="/struts-dojo-tags" %> to your page.
  • The head tag must be included on the page, which can be configured for performance or debugging purposes.
  • If the parseContent parameter for the head tag is false (it is false by default), then the id tag is required.

Additional Examples


For more examples see Ajax and JavaScript Recipes


The autocomplete tag is a combobox that can autocomplete text entered on the input box. If an action is used to populate the autocompleter, the output of the action must be a well formed JSON string.

The autocompleter follows this rule to find its datasource:

1. If the response is an array, assume that it contains 2-dimension array elements, like:

     ["Alabama", "AL"],
     ["Alaska", "AK"]

2. If a value is specified in the "dataFieldName" attribute, and the response has a field with that name, assume that's the datasource, which can be an array of 2-dimension array elements, or a map, like (assuming dataFieldName="state"):

     "state" : [
     "state" : {
           "Alabama" : "AL",
           "Alaska" : "AK"

3. If there is a field that starts with the value specified on the "name" attribute, assume that's the datasource, like (assuming name="state"):

     "states" : [

4. Use first array that is found, like:

     "anything" : [
           ["Alabama", "AL"],
           ["Alaska", "AK"]

5. If the response is a map, use it (recommended as it is the easiest one to generate):

     "Alabama" : "AL",
     "Alaska" : "AK"


Dynamic Attributes Allowed:








accesskeyfalsefalseStringSet the html accesskey attribute on rendered html element
afterNotifyTopicsfalsefalseStringComma delimmited list of topics that will published after the request(if the request succeeds)
autoCompletefalsefalsefalseBooleanWhether autocompleter should make suggestion on the textbox
beforeNotifyTopicsfalsefalseStringComma delimmited list of topics that will published before the request
cssClassfalsefalseStringThe css class to use for element
cssErrorClassfalsefalseStringThe css error class to use for element
cssErrorStylefalsefalseStringThe css error style definitions for element to use
cssStylefalsefalseStringThe css style to use for element
dataFieldNamefalseValue specified in 'name'falseStringName of the field in the returned JSON object that contains the data array
delayfalse100falseIntegerDelay before making the search
disabledfalsefalsefalseBooleanEnable or disable autocompleter
dropdownHeightfalse120falseIntegerDropdown's height in pixels
dropdownWidthfalsesame as textboxfalseIntegerDropdown's width
emptyOptionfalsefalseStringDecide if an empty option is to be inserted. Default false.
errorNotifyTopicsfalsefalseStringComma delimmited list of topics that will published after the request(if the request fails)
errorPositionfalsefalseStringDefine error position of form element (top|bottom)
forceValidOptionfalsefalsefalseBooleanForce selection to be one of the options
formFilterfalsefalseStringFunction name used to filter the fields of the form
formIdfalsefalseStringForm id whose fields will be serialized and passed as parameters
headerKeyfalsefalseStringSet the header key for the header option.
headerValuefalsefalseStringSet the header value for the header option.
hreffalsefalseStringThe URL used to load the options
iconPathfalsefalseStringPath to icon used for the dropdown
idfalsefalseStringThe id to use for the element
indicatorfalsefalseStringId of element that will be shown while request is made
javascriptTooltipfalsefalsefalseBooleanUse JavaScript to generate tooltips
keyfalsefalseStringSet the key (name, value, label) for this particular component
keyNamefalsefalseStringName of the field to which the selected key will be assigned
keyValuefalsefalseStringInitial key value
labelfalsefalseStringLabel expression used for rendering an element specific label
labelSeparatorfalse:falseStringString that will be appended to the label
labelpositionfalsefalseStringDefine label position of form element (top/left)
listfalsefalseStringIteratable source to populate from.
listKeyfalsefalseStringSet the key used to retrive the option key.
listValuefalsefalseStringSet the value used to retrive the option value.
listenTopicsfalsefalseStringTopic that will trigger a reload
loadMinimumCountfalse3falseIntegerMinimum number of characters that will force the content to be loaded
loadOnTextChangefalsetruefalseBooleanOptions will be reloaded everytime a character is typed on the textbox
maxLengthfalsefalseIntegerDeprecated. Use maxlength instead.
maxlengthfalsefalseIntegerHTML maxlength attribute
namefalsefalseStringThe name to set for element
notifyTopicsfalsefalseStringTopics that will be published when content is reloaded
onblurfalsefalseString Set the html onblur attribute on rendered html element
onchangefalsefalseStringSet the html onchange attribute on rendered html element
onclickfalsefalseStringSet the html onclick attribute on rendered html element
ondblclickfalsefalseStringSet the html ondblclick attribute on rendered html element
onfocusfalsefalseStringSet the html onfocus attribute on rendered html element
onkeydownfalsefalseStringSet the html onkeydown attribute on rendered html element
onkeypressfalsefalseStringSet the html onkeypress attribute on rendered html element
onkeyupfalsefalseStringSet the html onkeyup attribute on rendered html element
onmousedownfalsefalseStringSet the html onmousedown attribute on rendered html element
onmousemovefalsefalseStringSet the html onmousemove attribute on rendered html element
onmouseoutfalsefalseStringSet the html onmouseout attribute on rendered html element
onmouseoverfalsefalseStringSet the html onmouseover attribute on rendered html element
onmouseupfalsefalseStringSet the html onmouseup attribute on rendered html element
onselectfalsefalseStringSet the html onselect attribute on rendered html element
preloadfalsetruefalseBooleanLoad options when page is loaded
readonlyfalsefalsefalseBooleanWhether the input is readonly
requiredLabelfalsefalsefalseBooleanIf set to true, the rendered element will indicate that input is required
requiredPositionfalsefalseStringDefine required position of required form element (left|right)
resultsLimitfalse30falseIntegerLimit how many results are shown as autocompletion options, set to -1 for unlimited results
searchTypefalsestringstartfalseStringhow the search must be performed, options are: 'startstring', 'startword' and 'substring'
showDownArrowfalsetruefalseBooleanShow or hide the down arrow button
sizefalsefalseIntegerHTML size attribute
stylefalsefalseStringThe css style definitions for element to use - it's an alias of cssStyle attribute.
tabindexfalsefalseStringSet the html tabindex attribute on rendered html element
templatefalsefalseStringThe template (other than default) to use for rendering the element
templateCssPathfalsefalseStringTemplate css path
templateDirfalsefalseStringThe template directory.
titlefalsefalseStringSet the html title attribute on rendered html element
tooltipfalsefalseStringSet the tooltip of this particular component
tooltipConfigfalsefalseStringDeprecated. Use individual tooltip configuration attributes instead.
tooltipCssClassfalseStrutsTTClassicfalseStringCSS class applied to JavaScrip tooltips
tooltipDelayfalseClassicfalseStringDelay in milliseconds, before showing JavaScript tooltips
tooltipIconPathfalsefalseStringIcon path used for image that will have the tooltip
transportfalseXMLHTTPTransportfalseStringTransport used by Dojo to make the request
typefalsetextfalseStringSpecifies the html5 type element to display. e.g. text, email, url
valuefalsefalseStringPreset the value of input element
valueNotifyTopicsfalsefalseStringComma delimmited list of topics that will published when a value is selected


Get list from an action:

Uses a list:

Autocompleter that reloads its content everytime the text changes (and the length of the text is greater than 3):

Linking two autocompleters:

Set/Get selected values using JavaScript:

Using beforeNotifyTopics:

Using errorNotifyTopics:

Using errorNotifyTopics:

Using valueNotifyTopics:


  • The service that is producing the HTTP Response with JSON response to the Autocompleter tag must set the HTTP Header Response Content-Type to text/json. JSON has its own MIME type, which this tag expects.
  • Since 2.0.9, there is a change in the value:key order. Now, the value must come before the key.