List Box Usage Guideline Bookmark this Guideline Printable Page

RCUI Document Version 5.1.0 for Oracle® Fusion Middleware 11g Release 1 Patch Set 1 (
Last Updated 23-Feb-2011

The Select-One List Box allows users to review or select from a list of items. The Select-Many List Box allows users to pick one or more predefined values to populate a field or list.

Guideline Contents

Note: Images in this guideline are provided as a general reference, and may not be exact representations of FusionFX pages.

Related Guidelines

Guideline Section For Information About
Select Choice All Alternative to list boxes.
Select Radio All Alternative to Select-One List Boxes.
Checkbox All Alternative to Select-Many List Boxes.
Help Framework Note Windows Help method used with list boxes.
Message Framework All Message methods used with list boxes.
Form Layout All Commonly used to organize list boxes.
Headers Truncation Truncation of long values.

Related ADF Elements

Refer to the ADF Faces Rich Client demos page to find demos and tag documentation for the ADF elements related to this component:

ADF Element Notes
af:selectOneListbox Select-One List Box component.
af:selectManyListbox Select-Many List Box component.
af:selectItem List option component.

General Principles Bookmark this Heading Return to Top


  • Select-One List Box: allows users to select a single value from a predefined list.
  • Select-Many List Box: allows users to select one or more values from a predefined list.

Select-One List Box, showing some items grayed out, one item selected.       Select-Many List Box featuring listboxes for different beverage choices, and one box labeled 'All'.

Select-One List Box and Select-Many List Box


  • A list box is very similar in function to a Select Choice list. The key differences are that:
    • Select Choice lists require less space on the page, but require more clicks to select an option.
    • Select Choice lists are more suited for short lists of items.
    • List boxes display options directly on the page, so users can see some or all of them without using the mouse.
    • List boxes are more suitable when the number of options is likely to change over time.
    • For very long lists that may require searching, consider using a ListOfValues (LOV) component instead of a list box.
  • A list box may be used within a table cell or form layout. A list box may also be used as a stand-alone component.
  • Product teams can organize the contents of the list box by using a special sort order and group separators, or even a hierarchy (for select-one list boxes). See the Elements section for details.
  • If the list box is a required field and the user doesn't make a selection, then an error message should be displayed when the user attempts to apply changes to the page, just as with any other required field. See the Message Framework guideline for details.
  • A select-many list box functions like a select-one list box except that a select-many list box:
    • Contains check boxes next to each list option to enable multiple selection—both contiguous and non-contiguous.
    • May contain the option "All" to select all or none of the options in the list.
  • Do not use select-many list boxes with less than five options, unless the list of options will continue to increase over time. Instead, use a group of check boxes, or a select-many choice list.

Elements Bookmark this Heading Return to Top

Select-One List Box

The following image shows the elements of a select-one list box.

Elements of a Select-One List Box: changed field indicator or Help icon before the prompt, prompt, the list box, including a scroll bar, separators between items within the list, a sample of a disabled option, and a tooltip displayed on hover over an active option.

Elements in a Select-One List Box

Select-Many List Box

The following image shows the elements of a select-many list box.

Elements of a Select-Many List Box: Changed Field and Required Field indicators, the prompt, the 'Select All' region with its box checked at the top of the list, the list box itself, with scroll bar, separators between the list items, and a sample disabled option grayed out on the list.

Elements in a Select-Many List Box

Prompt Bookmark this Heading Return to Top


Identifies the objects contained in the list box.


  • Use of prompts is strongly recommended in a form layout. In a table layout, the column header is the prompt.
  • There is no limit to the number of characters allowed in the prompt, but product teams must make sure that the layout allows for prompts to become up to 100 percent longer in translation.
  • Prompts may be placed before or above a list box. Place the prompt before the list box in most cases. If horizontal space is an issue, such as inside an accordion panel, place the prompt above the list box.
  • Prompts may be visually omitted when the function of the list box is obvious to the product's users without displaying a label.
  • When a prompt is visually omitted, provide a hidden prompt label so that accessibility tools, such as screen readers, can still read a prompt for the data.
  • Prompts should use headline capitalization. See Capitalization in the Language in UI guideline for details.
  • Where possible, prompt text for select-many list boxes should be in plural form. For example, a select-many list box could have the plural prompt "Regions", but the equivalent select-one list box would have the singular prompt "Region".

Box Bookmark this Heading Return to Top


Displays the list of options.


  • By default, the width of the box is determined by the longest option in the panel. However, the width of the box can be set by product teams.
    • If the width of the box is set to be shorter than the length of the string of characters in the selected or default option, the option is clipped.
    • If it is necessary to set the width of the box to be shorter than the longest option, the width should list as many options as possible without clipping, and teams should supply the full text of clipped options in a tooltip.
    • Product teams may want to adjust the box width to align with other fields in a multiple column Form Layout, or to preserve a consistent width for the same type of field throughout an application.
  • By default, the height of the box displays four options. However, product teams can set the number of options displayed within the box.
    • When the list of options is long and the page layout will allow for a larger sized list box, increase the height of the list box to enable users to read as many options as possible without scrolling.
    • In products that require heavy, high-efficiency user interaction, such as data entry applications, set the box to be large enough to fit all options without displaying a scrollbar. In such products, users should not have to scroll to review all choices before making a selection.
  • The list box may be disabled when users are not able to select a value, but it is still necessary to display the list box because it may be enabled in different contexts.
  • The list box should be shown as read-only when data is displayed in a read-only page, such as a printable page. Read-only data may also be displayed when the user has permission to view the selected value, but not to edit it.
  • When a select-many box is read-only, the box does not display, and the selected options within the box show as plain text, delimited by semicolons.

List Options Bookmark this Heading Return to Top


Provide a range of choices to users.


Lists are similar for both types of list box, except the following behaviors are unique to the Select-Many List Box:

  • Clicking a list option toggles the selection for that option.
  • May have an "All" option that selects or deselects every item in the data set, even items that are outside of the viewable area of the panel.
  • In the read-only state, selections are shown in a semicolon-delimited list.
  • If an option contains a semicolon, the semicolon is escaped with a backslash (\) when it is shown in a read-only state, to distinguish its use as a character rather than as a delimiter. For example, if the user selects an option labeled "W;t", the option appears as "W\;t" when shown in a read-only state.


  • By default, no option is selected in the box, but product teams can set any option or options in a panel to be selected by default. For example, in an application configured for an audience in France, it may be appropriate to set the default value as "France" in a "Country" list.
    • For Select-Many list boxes use the "All" option when it is possible for all options to be selected. For example, when a user must set a preference for when to receive automated email alerts from a bug tracking system, the "Automated Alert Setting" field options could include options: "On bug status update," "On bug assignment revision," "On bug tracking group revision," or "All," where all choices are selected and activated.
  • List options should be should be arranged in a logical order:
    • For example, if a list contains values that represent different phases of a process, such as the phases of a publishing cycle (Draft, Internal Review, External Review, Editorial Review, and Published), display the values in sequence.
    • If the values represent value increments, such as smaller to larger, group them from smallest to largest in most cases, unless the opposite order makes more sense in a specific context.
    • If the values have some other generally recognized order, follow that order.
    • If there is no other logical order to the values, list them alphabetically or numerically; however, note that alphabetical ordering does not make sense in some languages, particularly Asian languages.
  • In select-one list boxes, text options may be indented using dashes to represent a hierarchy.
  • In select-one list boxes the option "None" may be used as a choice when appropriate. For example, if a user is creating a payment invoice and the process includes selecting a shipping address from a list, all predefined addresses may be in a list box. Some payments, however, are for service items that do not have physical goods to ship, and thus do not require shipping. In this case, a "None" option for the "Shipping Address" field may be used.
  • If users do not have the ability to change list box selection on a particular page, the selected list option or options should be displayed as read-only text after the list box prompt.
  • Display disabled options inside the list box when it is helpful for the user to see all options (both enabled and disabled) before making a selection. For example, a change request may have multiple states that are all displayed in the list (Pending, Approved, On hold, Rejected, and so on), but a user with limited privileges may be able to select only one or two of the states.
  • Options may have Description Text that appears in a tooltip on hover. See the Help Framework guideline for more details.
  • Blank options should not be used in a list box. Users may clear a list box selection by doing the following:
    • Select-one List Box: Ctrl+Click the selected option.
    • Select-many List Box: Clear the check box before the option.
  • List box options should be used for selections, not actions. Choosing options should neither navigate the user to a new page nor launch a dialog.

Separators Bookmark this Heading Return to Top


Divide options into groups.


A Human Resources application has a long list of forms available for employees, using separators to group similar or related options, such as:

  • Personal information
  • Vacation inquiry
  • Personal alerts
  • Online tax form (W4)
  • Online W2
  • Time card entry for payroll
  • Preview pay slip
  • Employee appraisal/review
  • Employee training request
  • Performance management


  • Separators organize long lists into sets of related options, making them easier for users to scan.
  • A separator must not follow another separator.
  • Separators must not be placed as the first or last item in the panel.
  • Clicking a separator should have no effect on the list box or any other element on the page.
  • There is no limit to the number of separators that may appear within a panel.
  • Finding the right level of balance in a long list can be a challenge. Too few or too many options in a group can make the list difficult to scan.
    • Where possible, do not group options in sets of one. If some options don't fit with anything else, consider merging the option with a related group, or placing them together in a "miscellaneous" group.
    • Where possible, do not group more than five options together.
  • When the "All" option is used in a select-many list box, it is always followed directly by a separator.

Required Field Indicator Bookmark this Heading Return to Top


Identifies fields that must be completed before submitting the page.


  • The Required Field Indicator is a text asterisk, *.
  • The Required Field Indicator does not display if a list box is disabled or read-only.


When creating a new service request, contact information is required for follow-up. In this case, product teams can make one of the contact fields required, such as such as "Region" or "Preferred Contact Method."


ADF provides ALT text and tooltips to indicate required fields. Product teams may additionally provide key notation to define the Required Field Indicator. Refer to Key Notation in the Headers guideline for information regarding usage.

Changed Field Indicator Bookmark this Heading Return to Top


Indicates that the value in the list box changed after page submission.


  • The changed field indicator should persist until the page is refreshed. If a scenario requires the indicator to persist after page refresh, the changed field indicator may remain displayed as long as needed. For example, when submitting an employee for a divisional transfer, a "Location" list box might display a changed field indicator once the final revision is submitted.
  • ADF provides ALT text and tooltips to indicate changed fields. Product teams may additionally provide key notation to define the Changed Field Indicator. Refer to Key Notation in the Headers guideline for information regarding usage.

Help Text Bookmark this Heading Return to Top


Provides users with additional information about the list box.


Help text should be provided when users may be unclear about the result of their choice, or may have difficulty choosing the correct option. See the Help Framework guideline for details.