Create new RichFaces Documentation Jira issue

This will launch the RichFaces Jira page - to complete your feedback please login if needed, and submit the Jira.

JBoss.orgCommunity Documentation

6.30.  < rich:comboBox >

The <rich:comboBox> is a component, that provides editable combo box element on a page.


Table 6.98. rich : comboBox attributes

Attribute NameDescription
bindingThe attribute takes a value-binding expression for a component property of a backing bean
buttonClassStyle Class attribute for the button
buttonDisabledClassStyle Class attribute for the disabled button
buttonDisabledStyleCSS style rules to be applied to disabled button
buttonIconDefines icon for the button element
buttonIconDisabledDefines disabled icon for the button element
buttonIconInactiveDefines inactive icon for the button element
buttonInactiveClassStyle Class attribute for the inactive button
buttonInactiveStyleCSS style rules to be applied to inactive button
buttonStyleCSS style rules to be applied to button
converterId of Converter to be used or reference to a Converter
converterMessageA ValueExpression enabled attribute that, if present, will be used as the text of the converter message, replacing any message that comes from the converter
defaultLabelDefines default label for the input field element
directInputSuggestionsDefines the first value from the suggested in input field. Default value is "false".
disabledWhen set for a form control, this boolean attribute disables the control for your input
enableManualInputEnables keyboard input, if "false" keyboard input will be locked. Default value is "true"
filterNewValuesDefines the appearance of values in the list. Default value is "true".
hideDelayDelay between losing focus and pop-up list closing. Default value is "0".
idEvery component may have a unique id that is automatically created if omitted
immediateA flag indicating that this component value must be converted and validated immediately (that is, during Apply Request Values phase), rather than waiting until a Process Validations phase
inputClassStyle Class attribute for the input field
inputDisabledClassStyle Class attribute for the disabled input
inputDisabledStyleCSS style rules to be applied to disabled input
inputInactiveClassStyle Class attribute for the inactive input
inputInactiveStyleCSS style rules to be applied to inactive input
inputStyleCSS style rules to be applied to input field
itemClassStyle Class attribute for the items
itemSelectedClassStyle Class attribute for the selected item
labelA localized user presentable name for this component.
listClassStyle Class attribute for the popup list
listHeightDefines height of file pop-up list. Default value is "200px".
listStyleCSS style rules to be applied to popup list
listWidthDefines width of file popup list
onblurThe client side script method to be called when the element loses the focus
onchangeThe client side script method to be called when the element value is changed
onclickThe clientside script method to be called when the element is clicked
ondblclickThe client side script method to be called when the element is double-clicked
onfocusThe client side script method to be called when the element gets the focus
onkeydownThe client side script method to be called when a key is pressed down over the element
onkeypressThe client side script method to be called when a key is pressed over the element and released
onkeyupThe client side script method to be called when a key is released
onlistcallThe clientside script method to be called when the list is called
onlistcloseThe clientside script method to be called when the list is closed
onmousedownThe client side script method to be called when a mouse button is pressed down over the element
onmousemoveThe client side script method to be called when a pointer is moved within the element
onmouseoutThe client side script method to be called when a pointer is moved away from the element
onmouseoverThe client side script method to be called when a pointer is moved onto the element
onmouseupThe client side script method to be called when a mouse button is released
onselectThe client side script method to be called when some text is selected in the text field. This attribute can be used with the INPUT and TEXTAREA elements.
renderedIf "false", this component is not rendered
requiredIf "true", this component is checked for non-empty input
requiredMessageA ValueExpression enabled attribute that, if present, will be used as the text of the validation message for the "required" facility, if the "required" facility is used
selectFirstOnUpdateDefines if the first value from suggested is selected in pop-up list. Default value is "true".
showDelayDelay between event and pop-up list showing. Default value is "0".
styleCSS style(s) is/are to be applied when this component is rendered
styleClassCorresponds to the HTML class attribute
suggestionValuesDefines the suggestion collection
tabindexThis attribute specifies the position of the current element in the tabbing order for the current document. This value must be a number between 0 and 32767. User agents should ignore leading zeros
validatorMethodBinding pointing at a method that is called during Process Validations phase of the request processing lifecycle, to validate the current value of this component
validatorMessageA ValueExpression enabled attribute that, if present, will be used as the text of the validator message, replacing any message that comes from the validator
valueThe current value of this component
valueChangeListenerListener for value changes
widthWidth of the component. Default value is "150".

Table 6.99. Component identification parameters

NameValue
component-typeorg.richfaces.ComboBox
component-classorg.richfaces.component.html.HtmlComboBox
component-familyorg.richfaces.ComboBox
renderer-typeorg.richfaces.renderkit.ComboBoxRenderer
tag-classorg.richfaces.taglib.ComboBoxTag

Here is a simple example as it could be used on a page:

Example:


...
<rich:comboBox value="#{bean.state}" suggestionValues="#{bean.suggestions}" />
...

Example:

import org.richfaces.component.html.HtmlComboBox;

... 
HtmlComboBox myComboBox = new HtmlComboBox();
...

The <rich:comboBox> is a simplified suggestion box component, that provides input with client side suggestions. The component could be in two states:

There are two ways to get values for the popup list of suggestions:

Popup list content loads at page render time. No additional requests could be performed on the popup calling.

The "value" attribute stores value from input after submit.

The "directInputSuggestions" attribute defines, how the first value from the suggested one appears in an input field. If it's "true" the first value appears with the suggested part highlighted.

Example:


...
<rich:comboBox value="#{bean.state}" suggestionValues="#{bean.suggestions}" directInputSuggestions="true" />            
...

This is a result:


The "selectFirstOnUpdate" attribute defines if the first value from suggested is selected in a popup list. If it's "false" nothing is selected in the list before a user hovers some item with the mouse.

Example:


...
<rich:comboBox value="#{bean.state}" suggestionValues="#{bean.suggestions}" selectFirstOnUpdate="false" />           
...

This is a result:


The "defaultLabel" attribute defines the default label of the input element. Simple example is placed below.

Example:


...
<rich:comboBox value="#{bean.state}" suggestionValues="#{bean.suggestions}" defaultLabel="Select a city..." />            
...

This is a result:


With the help of the "disabled" attribute you can disable the whole <rich:comboBox> component. See the following example.

Example:


...
<rich:comboBox value="#{bean.state}" suggestionValues="#{bean.suggestions}" defaultLabel="Select a city..." disabled="true" />            
...

This is a result:


The "enableManualInput" attribute enables/disables input field, so when enableManualInput = "false" , user can only pick the value manually and has no possibility to type in the value (default value is "false").

The <rich:comboBox> component provides to use specific event attributes:

  • "onlistcall" which is fired before the list opening and gives you a possibility to cancel list popup/update

  • "onselect" which gives you a possibility to send AJAX request when item is selected

The <rich:comboBox> component allows to use sizes attributes:

  • "listWidth" and "listHeight" attributes specify popup list sizes with values in pixels

  • "width" attribute customizes the size of input element with values in pixels.


For skinnability implementation, the components use a style class redefinition method. Default style classes are mapped on skin parameters.

There are two ways to redefine the appearance of all <rich:comboBox> components at once:















On the screenshot there are classes names that define styles for component elements.









In order to redefine styles for all <rich:comboBox> components on a page using CSS, it's enough to create classes with the same names (possible classes could be found in the tables above) and define necessary properties in them.

Example:


...
.rich-combobox-list-decoration{
        
background-color:#ecf4fe;
}
...

This is a result:


In the example background color for popup list was changed.

Also it's possible to change styles of particular <rich:comboBox> component. In this case you should create own style classes and use them in corresponding <rich:comboBox> styleClass attributes. An example is placed below:

Example:


...
.myClass{
        
font-weight:bold;
}
...

The "listClass" attribute for <rich:comboBox> is defined as it's shown in the example below:

Example:


<rich:comboBox ... listClass="myClass"/>

This is a result:


As it could be seen on the picture above, the font weight for items was changed.

On RichFaces LiveDemo page you can see an example of <rich:comboBox> usage and sources for the given example.