XML Syntax:
     <anyxmlelement xmlns:rich="" />

Represents self-contained and advanced UI components with out-of-the-box Ajax functionality.

Tag Library Information
Display Name RichFaces
Short Name rich

Tag Summary

The <rich:accordion> is a series of panels stacked on top of each other, each collapsed such that only the header of the panel is showing. When the header of a panel is clicked, it is expanded to show the content of the panel. Clicking on a different header will collapse the previous panel and expand the selected one. Each panel contained in a <rich:accordion> component is a <rich:accordionItem> component.

@author akolonitsky

The <rich:accordionItem> component is a panel for use with the <rich:accordion> component. <rich:accordionItem> components can be added dynamically using iteration models with the <c:forEach> tag.

@author akolonitsky

The <rich:autocomplete> component is an auto-completing input-box with built-in Ajax capabilities. It supports client-side suggestions, browser-like selection, and customization of the look and feel.

@author Nick Belaevski

The <rich:calendar> component allows the user to enter a date and time through an in-line or pop-up calendar. The pop-up calendar can navigate through months and years, and its look and feel can be highly customized.

@author amarkhel

The <rich:collapsiblePanel> component is a collapsible panel that shows or hides content when the header bar is activated. It is a simplified version of <rich:togglePanel> component.

@author akolonitsky

The <rich:collapsibleSubTable> component acts as a child element to a <rich:dataTable> component. The <rich:collapsibleSubTable> component iterates through the child collections in the currently iterated object to create master-detail tables.

@author Anton Belevich

The <rich:collapsibleSubTableToggler> component provides a toggle control for the user to expand and collapse sub-tables.

@author Anton Belevich

The <rich:column> component facilitates columns in a table. It supports merging columns and rows, sorting, filtering, and customized skinning.

@author Anton Belevich

The <rich:columnGroup> component combines multiple columns in a single row to organize complex parts of a table. The resulting effect is similar to using the breakRowBefore attribute of the <rich:column> component, but is clearer and easier to follow in the source code.


The <rich:componentControl> behavior allows JavaScript API functions to be called on target components. The functions are called after defined events are triggered on the component to with the <rich:componentControl> behavior is attached. Initialization variants and activation events can be customized, and parameters can be passed to the target component.

@author Anton Belevich

The <rich:contextMenu> component is used for creating a hierarchical context menu that are activated on events like onmouseover, onclick etc. The component can be applied to any element on the page.

@author Brian Leathem

The <rich:dataGrid> component is used to arrange data objects in a grid. Values in the grid can be updated dynamically from the data model, and Ajax updates can be limited to specific rows. The component supports header, footer, and caption facets.

@author Anton Belevich

The <rich:dataScroller> component is used for navigating through multiple pages of tables or grids.


The <rich:dataTable> component is used to render a table, including the table's caption. It works in conjunction with the <rich:column> and <rich:columnGroup> components to list the contents of a data model.

@author Anton Belevich

The <rich:dragIndicator> component defines a graphical element to display under the mouse cursor during a drag-and-drop operation.

@author abelevich

The <rich:dragSource> component can be added to a component to indicate it is capable of being dragged by the user. The dragged item can then be dropped into a compatible drop area, designated using the <rich:dropTarget> component.

@author abelevich
dropDownMenu The <rich:dropDownMenu> component is used for creating a drop-down, hierarchical menu. It can be used with the <rich:toolbar> component to create menus in an application's toolbar.

The <rich:dropTarget> component can be added to a component so that the component can accept dragged items. The dragged items must be defined with a compatible drop type for the <rich:dragSource> component.

@author abelevich

The <rich:editor> component is used for creating a WYSIWYG editor on a page.

@author Lukas Fryc

The <rich:extendedDataTable> component builds on the functionality of the <rich:dataTable> component, adding features such as scrolling for the table body (both horizontal and vertical), Ajax loading for vertical scrolling, frozen columns, row selection, and rearranging of columns. It also supports all the basic table features such as sorting, filtering, and paging using the <rich:dataScroller> component.

@author Konstantin Mishin

The <rich:fileUpload> component allows the user to upload files to a server. It features multiple uploads, progress bars, restrictions on file types, and restrictions on sizes of the files to be uploaded.

@author Konstantin Mishin

Focus component allows to set focus based on validation of components or alternatively it can preserve focus on currently focused form input.

Focus can be bound to form (in case of placement to h:form) or to whole view (when placed outside of forms) - in latter case, all forms will be managed by one Focus. There can be at most one Focus per form. When there is one view-scoped Focus and form defines own Focus, form-scoped Focus settings will be used.

Focus is applied each time the component is rendered - for each full page submit and for each partial page request (in case of ajaxRendered=true). Alternatively, you can use JavaScript API: applyFocus() function will immediately cause.


The <rich:graphValidator> component is used to wrap a set of input components related to one object. The object defined by the <rich:graphValidator> component can then be completely validated. The validation includes all object properties, even those which are not bound to the individual form components. Validation performed in this way allows for cross-field validation in complex forms.


The <rich:hashParam> component allows client-side parameters to be grouped into a hash map. The hash map can then be passed to the client JavaScript API functions of any RichFaces component.

@author Anton Belevich

The <rich:hotKey> component allows registering hot keys on the page or particular elements and defining client side processing functions for these keys.

@author ilya_shaikovsky @author Lukas Fryc

The <rich:inplaceInput> component allows information to be entered in-line in blocks of text, improving readability of the text. Multiple input regions can be navigated with keyboard navigation. The component has three functional states: the view state, where the component displays its initial setting, such as "click to edit"; the edit state, where the user can input text; and the "changed" state, where the new value for the component has been confirmed but can be edited again if required.

@author Anton Belevich

The <rich:inplaceSelect> component is similar to the <rich:inplaceInput> component, except that the <rich:inplaceSelect> component uses a drop-down selection box to enter text instead of a regular text field. Changes can be rendered either in-line or for the whole block, and inputs can be focused with keyboard navigation. The component is based on the JSF UISelectOne component, so all the standard rules for value definition, processing, conversion, and validation apply.

@author Anton Belevich
inputNumberSlider The <rich:inputNumberSlider> component provides a slider for changing numerical values. Optional features include control arrows to step through the values, a tool-tip to display the value while sliding, and a text field for typing the numerical value which can then be validated against the slider's range.
inputNumberSpinner The <rich:inputNumberSpinner> component is a single-line input field with buttons to increase and decrease a numerical value. The value can be changed using the corresponding directional keys on a keyboard, or by typing into the field.
itemChangeListener No Description

The <rich:jQuery> component applies styles and custom behavior to both JSF (JavaServer Faces) objects and regular DOM (Document Object Model) objects. It uses the jQuery JavaScript framework to add functionality to web applications.

This component is for use as a facelet tag. See the <rich:jQuery> EL function for access to the jQuery library via EL.

@author nick

The <rich:list> component renders a list of items. The list can be an numerically ordered list, an un-ordered bullet-point list, or a data definition list. The component uses a data model for managing the list items, which can be updated dynamically.


The <rich:menuGroup> component represents an expandable sub-menu in a menu control. The <rich:menuGroup> component can contain a number of <rich:menuItem> components, or further nested <rich:menuGroup> components.


The <rich:menuItem> component represents a single item in a menu control. The <rich:menuItem> component can be also be used as a seperate component without a parent menu component, such as on a toolbar.


The <rich:menuSeparator> component represents a separating divider in a menu control.


The <rich:message> component renders a single FacesMessage message instance added for the component. The appearance of the message can be customized, and tool-tips can be used for further information about the message.


The <rich:messages> components works similarly to the <rich:message> component, but can display all the validation messages added for the current view instead of just a single message.


The <rich:notify> component serves for advanced user interaction, using notification boxes to give the user instant feedback on what's happening within the application. Each time this component is rendered, a floating notification box is displayed in the selected corner of the browser screen.

@author Lukas Fryc @author Brian Leathem

The <rich:notifyMessage> component is built on top of <rich:notify>, the difference is in usage. The <rich:notifyMessage> component displays FacesMessages associated with a given component, similar to <rich:message>: one notification is displayed for first FacesMessage in the stack that is risen either programatically or during conversion/validation of the component. The severity of the message determines the color and icon of the resulting notification.

@author Lukas Fryc @author Brian Leathem

The <rich:notifyMessages> component is the same as the <rich:notifyMessage> component, but each of the available messages generates one notification.

@author Lukas Fryc @author Brian Leathem

Notifications emited by <rich:notify>, <rich:notifyMessage> and <rich:notifyMessages> are displayed in top-right corner of the screen by default.

It is <rich:notifyStack> which defines where messages will appear and handles their stacking.

Stack also provides way how to remove messages from screen - when stack is re-rendered, current notifications are destroyed, freeing place for new notifications.

@author Bernard Labno @author Lukas Fryc

The <rich:orderingList> is a component for ordering items in a list (client-side).

@author Brian Leathem

The <rich:panel> component is a bordered panel with an optional header.


The <rich:panelMenu> component is used in conjunction with <rich:panelMenuItem> and <rich:panelMenuGroup> to create an expanding, hierarchical menu. The <rich:panelMenu> component's appearance can be highly customized, and the hierarchy can stretch to any number of sub-levels.

@author akolonitsky

The <rich:panelMenuGroup> component defines a group of <rich:panelMenuItem> components inside a <rich:panelMenu>.

@author akolonitsky

The <rich:panelMenuItem> component represents a single item inside a <rich:panelMenuGroup> component, which is in turn part of a <rich:panelMenu> component.

@author akolonitsky
panelToggleListener No Description

The <rich:pickList> is a component for selecting items from a list. Additionally, it allows for the selected items to be ordered (client-side). From the client side perspective, items are added/removed from the source list, and removed/added to the target list.

@author Brian Leathem
placeholder Adds placeholder capability to HTML input and textarea elements. A placeholder typically appears as light gray text within an input or textarea element whenever the element is empty and does not have focus. This provides a hint to the user as to what the input or textarea element is used for, or the type of input that is required.

The <rich:popupPanel> component provides a pop-up panel or window that appears in front of the rest of the application. The <rich:popupPanel> component functions either as a modal window which blocks interaction with the rest of the application while active, or as a non-modal window. It can be positioned on the screen, dragged to a new position by the user, and re-sized.


The <rich:progressBar> component displays a progress bar to indicate the status of a process to the user. It can update either through Ajax or on the client side, and the look and feel can be fully customized.

@author "Andrey Markavtsov"

The <rich:select> component provides a drop-down list box for selecting a single value from multiple options. The <rich:select> component can be configured as a combo-box, where it will accept typed input. The component also supports keyboard navigation. The <rich:select> component functions similarly to the JSF UISelectOne component.

@author abelevich

The <rich:tab> component represents an individual tab inside a <rich:tabPanel> component, including the tab's content. Clicking on the tab header will bring its corresponding content to the front of other tabs.

@author akolonitsky

The <rich:tabPanel> component provides a set of tabbed panels for displaying one panel of content at a time. The tabs can be highly customized and themed. Each tab within a <rich:tabPanel> container is a <rich:tab> component.

@author akolonitsky

The <rich:toggleControl> behavior can be attached to any interface component, whether inside or outside the controlled panel itself. It works with a <rich:togglePanel> component to switch between different <rich:togglePanelItem> components.

@author akolonitsky

The <rich:togglePanel> component is used as a base for the other switchable components, the <rich:accordion> component and the <rich:tabPanel> component. It provides an abstract switchable component without any associated markup. As such, the <rich:togglePanel> component could be customized to provide a switchable component when neither an accordion component or a tab panel component is appropriate.

@author akolonitsky @author Brian Leathem

The <rich:togglePanelItem> component is a switchable panel for use with the <rich:togglePanel> component. Use the <rich:togglePanelItem> component to define the content for a panel using nested components. Switching between <rich:togglePanelItem> components is handled by the <rich:toggleControl> behavior.

@author akolonitsky @author Brian Leathem

The <rich:toolbar> component is a horizontal toolbar. Any JavaServer Faces (JSF) component can be added to the toolbar.


The <rich:toolbarGroup> component is a child component of the <rich:toolbar> component. The <rich:toolbarGroup> component is used to group a number of items together on a toolbar.


The <rich:tooltip> component provides an informational tool-tip. The tool-tip can be attached to any control and is displayed when hovering the mouse cursor over the control.

@author amarkhel

The <rich:tree> component provides a hierarchical tree control. Each <rich:tree> component typically consists of <rich:treeNode> child components. The appearance and behavior of the tree and its nodes can be fully customized.

@author Nick Belaevski
treeModelAdaptor The component takes an object which implements the Map or Iterable interfaces. It adds all the object entries to the parent node as child nodes. @author Nick Belaevski

The component iterates through recursive collections in order to populate a tree with hierarchical nodes, such as for a file system with multiple levels of directories and files.

@author Nick Belaevski

The component is a child component of the component. It represents nodes in the parent tree. The appearance and functionality of each tree node can be customized.

@author Nick Belaevski
treeSelectionChangeListener No Description
treeToggleListener No Description

The <rich:validator> behavior adds client-side validation to a form input control based on registered server-side validators. It provides this validation without the need to reproduce the server-side annotations.

The <rich:validator> behavior triggers all client validator annotations listed in the relevant managed bean.


Function Summary
java.lang.String clientId ( java.lang.String) The rich:clientId('id') function returns the client identifier related to the passed component identifier ('id'). If the specified component identifier is not found, null is returned instead.
java.lang.String component ( java.lang.String) The rich:component('id') function is equivalent to the RichFaces.$('clientId') code. It returns the client object instance based on the passed server-side component identifier ('id'). If the specified component identifier is not found, null is returned instead. The function can be used to get an object from a component to call a JavaScript API function without using the component.
java.lang.String element ( java.lang.String)

The rich:element('id') function is a shortcut for the equivalent document.getElementById(#{rich:clientId('id')}) code. It returns the element from the client, based on the passed server-side component identifier. If the specified component identifier is not found, null is returned instead.

javax.faces.component.UIComponent findComponent ( java.lang.String) The rich:findComponent('id') function returns the a UIComponent instance of the passed component identifier. If the specified component identifier is not found, null is returned instead.
boolean isUserInRole ( java.lang.Object)

The rich:isUserInRole(Object) function checks whether the logged-in user belongs to a certain user role, such as being an administrator. User roles are defined in the web.xml settings file.

@since 3.3.1
java.lang.String jQuery ( java.lang.String)

The rich:jQuery('id') function is a shortcut for the equivalent jQuery(#{rich:element('id')}) code. It returns the jQuery object from the client, based on the passed server-side component identifier. If the specified component identifier is not found, empty jQuery object is returned instead.

This function is for use in EL. Refer to the <rich:jQuery> component for access to the jQuery library as a facelet tag.

java.lang.String jQuerySelector ( java.lang.String) The rich:jQuerySelector('id') function will perform nearly the same function as rich:clientId('id') but will transform the resulting id into a jQuery id selector which means that it will add a "#" character at the beginning and escape all reserved characters in CSS selectors.
java.lang.String toScript ( java.lang.Object) Convert any Java Object to JavaScript representation, converting types properly, e.g.:
  • Java primitives
  • Arrays: toScript(new int[] { 1, 2, 3 }) -> [1, 2, 3]
  • Collections (sets, lists): toScript(Arrays.asList(new int[] { 1, 2, 3 })) -> [1, 2, 3]
  • Maps: toScript((Map<String, String>)map) -> {\"a\":\"foo\",\"b\":\"bar\",\"c\":\"baz\"}
  • Beans / Objects: toScript(new Bean[] { new Bean(1, true, "bar") }) -> [{\"bool\":true,\"foo\":\"bar\",\"integer\":1}]
  • Dates and Timezones
  • Combinations of above
This function delegates to org.ajax4jsf.javascript.ScriptUtils#toScript(Object)

Java, JSP, and JavaServer Pages are trademarks or registered trademarks of Sun Microsystems, Inc. in the US and other countries. Copyright 2002-3 Sun Microsystems, Inc. 4150 Network Circle Santa Clara, CA 95054, U.S.A. All Rights Reserved.