DropDownField

The DropDownField is an input component which allows either type in a value or select one of the values from an attached drop-down list. The component provides a way to show a list of suggestions based on user input and the ability to auto-complete user input in the input field. The drop-down list can be displayed in multiple columns and contain other JSF components.


API Reference | Tag Reference
Online Demo

Key Features

Specifying List of Items

To add the DropDownField component to a page, use the <o:dropDownField> tag. There are three ways to specify items that will be displayed in the drop-down list. Regardless of the way you choose, each item is assigned a value that becomes a selected value of the DropDownField component once an appropriate item is selected. The item value can either be a String or an arbitrary Object. See the Entering Non-String Values section for details of setting up the DropDownField component for selection from a list of Objects rather than Strings.

You can specify drop-down list items in the following ways:

  • Create a fixed list of values right on the JSF page. To do so, you should use the <o:dropDownItem> tag to specify each separate item. The value attribute of the <o:dropDownItem> tag can either be a String literal, which specifies a string value for this item, or a value binding expression, which refers to an Object that will be the value for this item. The example below shows the DropDownField component containing three items in the list.
<o:dropDownField>
  <o:dropDownItem value="Red"/>
  <o:dropDownItem value="Yellow"/>
  <o:dropDownItem value="Blue"/>
</o:dropDownField>


It is also possible to add child components to the <o:dropDownItem> tag. The following example demonstrates this feature using color definitions along with their names. Note that when a color is selected (for example, "Red"), the text field will display not the name of the color, but its hexadecimal value (#FF0000).

<o:dropDownField>
  <o:dropDownItem value="#FF0000" >
    <h:graphicImage url="/important.gif"/>
    <h:outputText value="Red"/>
  </o:dropDownItem>
  <o:dropDownItem value="#FFFF00">
    <h:outputText value="Yellow"/>
  </o:dropDownItem>
  <o:dropDownItem value="#0000FF">
    <h:outputText value="Blue"/>
  </o:dropDownItem>
</o:dropDownField>
  • Retrieve the list of items from a backing bean. To do so, you should use the <o:dropDownItems> tag. The value attribute of the <o:dropDownItems> tag should be bound to the collection or array of org.openfaces.component.input.DropDownItem instances or item value objects:
    <o:dropDownField>
      <o:dropDownItems value="#{DropDownBackingBean.dropDownItems}"/>
    </o:dropDownField>

    And here's how the dropDownItems property is defined in the DropDownBackingBean class:

    public List getDropDownItems() {
      List itemValues = Arrays.asList(new String[]{"Red", "Yellow", "Blue"});
      return itemValues;
    }
  • Combine the two aforementioned approaches by specifying the <o:dropDownItem> and <o:dropDownItems> tags in any order you need.

    Note
    You can specify only non-null item value objects in any approach you use to specify drop-down list items.

A selected value of the DropDownField component can be maintained using the value attribute of <o:dropDownField> tag. The usage of this attribute is similar to that in standard JSF input components such as <h:inputText> or <h:selectOneMenu>. This attribute should be bound to either a String or an Object attribute depending on the type of item value objects. See the Entering Non-String Values section for details of entering non-string values in the DropDownField component.

Here's an example of using the value attribute.

<o:dropDownField value="#{DropDownBackingBean.selectedColor}>
  <o:dropDownItem value="Red"/>
  <o:dropDownItem value="Yellow"/>
  <o:dropDownItem value="Blue"/>
</o:dropDownField>

You can specify the prompt text for the DropDownField component using the promptText attribute.
The prompt text is a label or short instruction placed inside the DropDownField component.The specified text will be shown to the user while the value of the DropDownField component is empty and disappear from the screen once user types something into the DropDownField or it gets input focus.

<o:dropDownField value="#{DropDownBackingBean.selectedColor} promptText="Specify the color">
  <o:dropDownItem value="Red"/>
  <o:dropDownItem value="Yellow"/>
  <o:dropDownItem value="Blue"/>
</o:dropDownField>

You can customize the styles of the prompt text by using the promptTextStyle and promptTextClass attributes.

Like any JSF UIInput component, the DropDownField component supports the standard validator, required, converter, immediate and disabled attributes. For more information about them, see JavaServer Faces specification (section "EditableValueHolder").

Restricting Input to List Items

The DropDownField component is an input component where the user can enter a value either by typing it in or by selecting it from the drop-down list. So it acts as a combination of an ordinary input field (such as <h:inputText>) and a combo-box component (such as <h:selectOneMenu>). Therefore, unlike the usual combo-box component, the user can type in any value, not necessarily available in the drop-down list. In some cases, it may be required to restrict the input only to the values from the predefined list, which means that a component should act like a combo-box.

The DropDownField component provides this ability while also enabling you to use features like auto-suggestion and auto-completion and many others. This behavior can be triggered by setting the customValueAllowed attribute to "false". This attribute defines whether it is possible to specify only a value that exists in the list of drop-down items ("false") or whether it is possible to enter any value ("true").

Entering Non-String Values

With the DropDownField component, you can enter non-string values, too. For instance, you may need to select an object from a set of JavaBean objects read from the database. In this case, you will need to specify these non-string objects as the drop-down list item values (using <o:dropDownItem> or <o:dropDownItems> tags). In addition, the following requirements must be met:

  • The DropDownField component's value attribute should be bound to a property having the type of objects you are selecting from.
  • A converter for the appropriate type of objects should be specified. It can either be specified using the DropDownField component's converter attribute, or there should be an application-wide converter for this type. The converter is used for both converting a selected item for display in the field and converting the entered text value back to the appropriate object type.

Specifying Child Components

From the previous section, you already know that you can specify any child components within the DropDownItem component. However, DropDownItem components are used only when you have a fixed number of items. For a dynamic or big set of items, it is more suitable to use the DropDownItems component, which cannot include child components. However, if you need to specify a set of components that should be rendered inside of all items, you can specify these components as children of the <o:dropDownField> tag.

Child components of the <o:dropDownField> tag are used to render each drop-down item. Note that the same child components of the DropDownField are rendered in every drop-down item. So in order for these components to display different data for each respective item, you should use a request-scope variable referring to the current item value object. The item value object is an object that you specify in the corresponding <o:dropDownItem> tag or an entry in the <o:dropDownItems> collection or array. The name of this variable should be specified using the var attribute of the <o:dropDownField> tag.

The following example shows the DropDownField component specified using child components:

<o:dropDownField value="#{DropDownBean.selectedBGColor}"
                 var="color"
                 converter="#{DropDownBean.colorConverter}">
  <o:dropDownItems value="#{DropDownBean.colors}"/>

  <h:outputText styleClass="colorRect" style="background: #{color.name};"/>
  <h:outputText value="#{color.name}"/>
</o:dropDownField>

It is also possible to use child components of the DropDownField component with the DropDownItem components. The values of the DropDownItem components are available using a request-scope variable specified in the var attribute of the <o:dropDownField> tag.

Here is an example of specifying child components of the DropDownField component with the <o:dropDownItem> tags:

<o:dropDownField value="#{DropDownBean.selectedFont}"
                 var="size">
  <o:dropDownItem value="9pt"/>
  <o:dropDownItem value="10pt"/>
  <o:dropDownItem value="12pt"/>
  <o:dropDownItem value="14pt"/>
  <o:dropDownItem value="16pt"/>
  <o:dropDownItem value="18pt"/>
  <o:dropDownItem value="20pt"/>

  <h:outputText value="#{size}" style="font-size: #{size};"/>
</o:dropDownField>

Note that if you specified child components both for <o:dropDownItem> and <o:dropDownField>, the components specified in the <o:dropDownItem> tag take priority over the components specified for all items, and only the children of the respective <o:dropDownItem> tag are displayed for such items.

Creating Multi-Column Drop-Down List

The DropDownField component lets you specify a drop-down list to be displayed in multiple columns. The list of columns is specified using the <o:column> tags within the <o:dropDownField> tag. Child components of the <o:column> tag are used to render each cell of the current item just like in the <o:dataTable> component. As in case of specifying child components described in the previous section, you should use a request-scope variable referring to the current item data in order for child components to display different data for each respective item. 

You can specify the "header" and "footer" facets , styles and client-side events for the <o:column> tag. Also, the <o:column> tag has the width, align and valign attributes that are rendered onto the <col> tag of the respective column. In addition, it is possible to group several columns using the <o:columnGroup> tag and add additional group headers. For more details about the <o:column> and <o:columnGroup> tags, see the DataTable component documentation.

Here's an example of specifying a multi-column drop-down list in the DropDownField component:

<o:dropDownField value="#{DropDownBean.selectedBGColor}"
                 var="color"
                 converter="#{DropDownBean.colorConverter}">
  <o:dropDownItems value="#{DropDownBean.colors}"/>
  <o:column width="12px">
    <h:outputText styleClass="colorRect" style="background: #{color.name};"/>
  </o:column>
  <o:column>
    <h:outputText value="#{color.name}"/>
  </o:column>
</o:dropDownField>

Auto-Suggestion

The DropDownField component can be configured to display a list of suggestions based on the input entered partially by the user. When this feature is turned on, the list of suggestions is updated on-the-fly as the user types text, and the user can select one of the provided suggestions any time when appropriate. This feature makes it easier to find items by typing only part of their text. You can turn on the auto-suggestion feature with the suggestionMode attribute. By default, this attribute is set to "none", which means that this feature is turned off.

The DropDownField component supports different auto-suggestion modes, each of which can be specified using one of the following values:

  • "stringStart" - Shows suggestions that begin with the entered value (works on the client side.)
  • "substring" - Shows suggestions that contain the entered value (works on the client side.)
  • "stringEnd" - Shows suggestions that end with the entered value (works on the client side.)
  • "all" - Shows all drop-down items in the list of suggestions (works on the client side.)
  • "custom" - Sends an Ajax request when the user is entering a value and returns a list of suggestions from the server (works on the server side using Ajax.)

The first four auto-suggestion modes work on client side and can be used to introduce the most robust suggestion functionality because no server round-trips are required in this case. However, this way is not efficient in case of large lists, because all of the suggestions must be preloaded on the client in these modes. To avoid resource-intensive preloading as well as to implement more flexible auto-suggestion scenarios, you can take advantage of the "custom" suggestion mode.

When you use the "custom" suggestion mode, the value attribute of the DropDownItems components should be bound to the method that returns the list of suggestions corresponding to the entered string. You can get the entered value from the DropDownField component using the "searchString" request-scope variable. To retrieve a variable by its name, you can use the org.openfaces.util.Faces.var(String varName) method. Note that the "searchString" variable can have a null value. The null value is passed when requesting the default suggestion items that should be shown by manual opening the DropDownField without typing any text.

The example below shows usage of the "custom" auto-suggestion mode:

<o:dropDownField value="#{DropDownBean.city}"
                 converter="#{DropDownBean.cityNameConverter}"
                 suggestionMode="custom">
  <o:dropDownItems value="#{DropDownBean.cities}"/>
</o:dropDownField>

Here is how the above example can be implemented in the backing bean:

public List getCities() {
  String searchString = Faces.var("searchString", String.class);
  List filteredCities = searchString == null
    ? myCitiesDB.getDefaultCities()
    : myCitiesDB.findCitiesStartingWithText(searchString);
  return filteredCities;
}


There are two attributes that control how auto-suggestion and auto-completion features are activated. The integer suggestionMinChars attribute specifies the minimum number of characters that should be typed for auto-completion and auto-suggestion features to be activated. By default, the suggestionMinChars attribute is set to 0, which means that drop-down suggestion list appears after the user types at least one character and remains opened when the user clears the typed text.

You can set a delay that should elapse after the last key press before starting auto-suggestion and auto-completion. The time period for this delay should be specified for the suggestionDelay attribute in milliseconds (by default, "350"). This attribute is particularly useful when it's necessary to avoid too many Ajax requests that are sent to the server while the user is typing text. With the suggestionDelay attribute, you send only one Ajax request when the user has stopped typing.

Here's an example of using the suggestionMinChars and suggestionDelay attributes:

<o:dropDownField value="#{DropDownBean.selectedBGColor}"
                 var="color"
                 suggestionMode="custom"
                 suggestionDelay="200"
                 suggestionMinChars="3"
                 converter="#{DropDownBean.colorConverter}">
...
</o:dropDownField>

Auto-Completion

The DropDownField component provides the auto-completion feature which in addition to auto-suggestion can be used to simplify selection of a value among the items specified with the <o:dropDownItem> or <o:dropDownItems> tags. When auto-completion is turned on, the DropDownField component completes partially entered text in the input field. The text is completed to the first drop-down item that starts with the typed text. The part added as a result of auto-completion is marked as selected.

The auto-completion feature can be turned on by setting the autoComplete attribute to "true" (default is "false"). Auto-completion, like the auto-suggestion feature, also depends on the suggestionMinChars and suggestionDelay attributes, described in the previous section.

Below is an example of using the autoComplete attribute:

<o:dropDownField value="#{DropDownBean.selectedBGColor}"
                 var="color"
                 autoComplete="true"
                 suggestionDelay="200"
                 suggestionMinChars="3"
                 converter="#{DropDownBean.colorConverter}">
...
</o:dropDownField>

Keyboard Navigation

The DropDownField component supports keyboard navigation. The user can open a drop-down list by using the Down Arrow key. After opening a drop-down list, the user can navigate between drop-down items with the Up Arrow, Down Arrow, Home, End, Page Up, Page Down keys and then select an item with the Enter key. To close the list without changing the value, the user can press the Esc key.

Auto-Closing Drop-Down List

By default, the drop-down list in the DropDownField component behaves like an ordinary combo box, i.e. it is hidden until the user clicks the drop-down button. Once the list is opened, it remains visible until the user selects an item or closes the list explicitly. To close the list without changing the value, the user can either press the Esc key or click anywhere outside of the component. However, in addition to the ability to close the drop-down list manually, you can specify a time period after which the list is closed automatically. To do so, set the time (in milliseconds) in the timeout attribute. The value of timeout equal to -1 (default) means that the drop-down list should not be closed automatically.

In the example below, the drop-down list closes in 3000 milliseconds (or 3 seconds):

<o:dropDownField timeout="3000">
  <o:dropDownItems value="#{DropDownBackingBean.dropDownItems}"/>
</o:dropDownField>

Customizing Appearance

You can set an image for the drop-down button by using the buttonImageUrl attribute. The buttonAlignment attribute lets you specify whether the drop-down button is positioned to the right or to the left of the component. This attribute can take the "right" or "left" values only. The default location of the button is to the right of the input field.

In the example below, the drop-down button is left-aligned:

<o:dropDownField buttonAlignment="left"/>

In most cases, the width of the drop-down list is the same as the width of the DropDownField component itself. However, if the content of the list is too wide to fit in the DropDownField, the width of the drop-down list can exceed the width of the component. In this case, you can specify alignment of the drop-down list with the listAlignment attribute by setting its value to "left" (default) or "right". The default left alignment means that the left edge of the drop-down list is aligned with the left edge of the DropDownField component.

The following example shows the DropDownField component with a right-aligned drop-down list.

<o:dropDownField listAlignment="right">
...
</o:dropDownField>

You can specify the maximum height and width of the drop-down list using the height and width properties of the listStyle attribute. If the number of drop-down items is too large to fit in the height of the drop-down list, a scroll is added.

Like the HTML <input> tag, <o:dropDownField> supports the title, tabindex, accesskey, and maxlength attributes. These attributes are rendered for a nested input field of the DropDownField component. Note that the maxlength attribute affects only the maximum number of characters that a user can type, but it is still possible to select any text from the drop-down list no matter how long it is.

Customizing Styles

You can apply styles for any part of the DropDownField component, both when it's in the normal and rollover states. The table below lists all style attributes:

Part of component Style attributes Class attributes Rollover style attributes Rollover class attributes Focused style attributes Focused class attributes
Entire DropDownField component style styleClass rolloverStyle rolloverClass focusedStyle focusedClass
Input field fieldStyle fieldClass rolloverFieldStyle rolloverFieldClass - -
Drop-down button buttonStyle buttonClass rolloverButtonStyle rolloverButtonClass - -
Pressed drop-down button pressedButtonStyle pressedButtonClass - - - -
Drop-down list listStyle listClass rolloverListStyle rolloverListClass - -
List item listItemStyle listItemClass rolloverListItemStyle rolloverListItemClass - -
Odd list item, if different from listItemStyle oddListItemStyle oddListItemClass - - - -
Header row in a multi-column drop-down list
listHeaderRowStyle listHeaderRowClass - - - -
Footer row in a multi-column drop-down list listFooterRowStyle listFooterRowClass - - - -

This example shows usage of one class attribute and two style attributes for the DropDownField component.

.dropDownList {
   background-color: red;
   }
...
<o:dropDownField
        style="border-style: solid; border-width: 1px; border-color: silver;"
        listClass="dropDownList"
        rolloverButtonStyle="background-color: #ECECEC;">
  <o:dropDownItems value="#{DropDownBackingBean.dropDownItems}"/>
</o:dropDownField>

When you need to customize styles for grid lines in a multi-column drop-down list, use the following attributes:

Horizontal lines in the drop-down list horizontalGridLines
Vertical lines in the drop-down list verticalGridLines
A line that separates the header from drop-down items headerHorizSeparator
Vertical lines between column headers headerVertSeparator
A line that separates the footer from drop-down items footerHorizSeparator
Vertical lines between column footers footerVertSeparator

Note
All style attributes for a multi-column drop-down list should be specified as the CSS "border" property but without the prefix "border:".

Here's an example of applying styles to the grid lines of the drop-down list:

<o:dropDownField value="#{DropDownBean.selectedColor}"
                 horizontalGridLines="1px dotted gray"
                 verticalGridLines="1px dotted gray"
                 headerHorizSeparator="3px solid gray"
                 headerVertSeparator="1px solid gray"
                 footerHorizSeparator="3px solid gray"
                 footerVertSeparator="1px solid gray">
  ...
</o:dropDownField>

Client-Side Events

The DropDownField component supports the following standard client-side events: onchange, onkeypress, onclick, ondblclick, onmousedown, onmouseover, onmouseup, onmouseout, onmousemove, onfocus, onblur, onkeydown, onkeyup.

Please note that the mouse events work for the entire DropDownField component except for the drop-down list, while the keyboard events also work for the drop-down list. In addition, the DropDownField component provides two specific events:

Event name Description
ondropdown Occurs when the drop-down list is opened.
oncloseup Occurs when the drop-down list is closed.

Server-Side Event Listeners

Given that the DropDownField component is a UIInput component, it can fire javax.faces.event.ValueChangeEvent just like any other UIInput component does. To handle a value change event on the server side, the valueChangeListener attribute should be used in the same way as for the HTMLInputText component. You can also add a value change listener to the component by using the <f:valueChangeListener> tag.

Client-Side API

All client-side API methods for the DropDownField component are listed below:

Method Description
getValue() Gets the value from the DropDownField component on which this method is invoked.
setValue (value) Sets the value for the DropDownField component on which this method is invoked.
dropDown() Opens the drop-down list for the DropDownField component on which this method is invoked.
closeUp() Closes the drop-down list for the DropDownField component on which this method is invoked.
isOpened() Returns "true" if the drop-down list is opened.
OpenFaces