Listbox

Employment/Purpose

Components: listbox, listitem, listcell, listhead and listheader.

A list box is used to display a number of items in a list. The user may select an item from the list. Although listhead is optional, if it exists, notice that the number of listheader should equal the number of listcell, so that listbox can display its content correctly. If listhead contains no listheader, the listbox will display nothing in its content.

Example

 <window title="listbox demo" border="normal" width="250px">
    <listbox id="box">
        <listhead sizable="true">
            <listheader label="name" sort="auto" />
            <listheader label="gender" sort="auto" />
        </listhead>
        <listitem>
            <listcell label="Mary" />
            <listcell label="FEMALE" />
        </listitem>
        <listitem>
            <listcell label="John" />
            <listcell label="MALE" />
        </listitem>
        <listitem>
            <listcell label="Jane" />
            <listcell label="FEMALE" />
        </listitem>
        <listitem>
            <listcell label="Henry" />
            <listcell label="MALE" />
        </listitem>
        <listfoot>
            <listfooter>
                <label value="This is footer1" />
            </listfooter>
            <listfooter>
                <label value="This is footer2" />
            </listfooter>
        </listfoot>
    </listbox>
</window>

Listboxes Contain Buttons

In theory, a list cell can contain any other components, as demonstrated below.

 
<zk>
    <listbox width="250px">
        <listhead>
            <listheader label="Population"/>
            <listheader label="Percentage"/>
        </listhead>
        <listitem value="A">
            <listcell><textbox width="90%" value="A. Graduate"/></listcell>
            <listcell label="20%"/>
        </listitem>
        <listitem value="B">
            <listcell><checkbox label="B. College"/></listcell>
            <listcell><button label="23%"/></listcell>
        </listitem>
        <listitem value="C">
            <listcell label="C. High School"/>
            <listcell><textbox cols="8" value="40%"/></listcell>
        </listitem>
    </listbox>
</zk>

Notes:

  1. Don’t use a list box, when a grid is a better choice. The appearances of list boxes and grids are similar, but the listbox should only be used to represent a list of selectable items.
  2. Users are usually confused if a listbox contains editable components such as a textbox or a checkbox.
  3. Due to the limitation of the browsers, users cannot select a range of characters from text boxes.

Mold

The Listbox has two molds: default and select.

Select Mold

Suggest using Selectbox.

If the select mold is used, Listbox renders an HTML <select> tag instead.

 
    <listbox mold="select">
        <listitem label="Matthew"/>
        <listitem label="Macus"/>
        <listitem label="Lucas"/>
        <listitem label="John"/>
    </listbox>

Note: if the mold is “select”, rows is “1”, and none of the items are marked as selected, the browser will display the listbox as if the first item is selected. Worst of all, if the user selects the first item in this case, no onSelect event is sent. To avoid this confusion, developers should select at least one item when using mold="select" and rows="1".

In addition to each item’s label, you can assign an application-specific value to each item using the setValue method.

is not supported in this mold. ### Listgroup Supported since 8.6 This mold supports having Listgroups and renders them as HTML . ![](/zk_component_ref/images/Select-mold-optgroup.png) ```xml ```
'''Notice:''' Listbox doesn't send onClick event for listitem under this mold.
# Keyboard Navigation Listbox - Press `UP` and `DOWN` to move the selection up and down by one list item. - Press `PgUp` and `PgDn` to move the selection up and down by one page. - Press `HOME` to move the selection to the first item, and `END` to move to the last item. - Press `Ctrl+UP` and `Ctrl+DOWN` to move the focus up and down by one list item without changing the selection. - Press `SPACE` to select the item in focus. # Paging Like grids, you can use multiple pages to represent large content by setting the mold to `paging`. Similarly, you can control how many items each page displays, whether to use an external paging component and whether to customize the behavior when a page is selected. The `listbox` and `grid` components support the paging intrinsically, so you don't need to specify a paging component explicitly as above unless you want to have different visual layout or to control multiple `listbox` and `grid`controls with one paging component. Please refer to the [ Grid](/zk_component_ref/data/grid#Paging) for more details. ## Autopaging When using the paging mold and vflex, you can also turn on autopaging (org.zkoss.zul.Listbox) such that Listbox will determine the page size automatically based on the available height.
'''Notice:''' This feature only works when each row has the same height.
since 5.0 **Note:** If the autopaging is enabled, the height of each row will be applied the following CSS by default. If you want to change the height, please overwrite the CSS rule as your preference. ```css .z-listbox-autopaging .z-listcell-cnt { height: 30px; overflow: hidden; } ``` since 5.0 **Note:** In ZK 7, we change the naming *.z-listcell-cnt* to *.z-listcell-content*. since 7.0 ```css .z-listbox-autopaging .z-listitem { height: 80px; /* set custom height */ } .z-listbox-autopaging .z-listcell-content { height: auto; /* remove the default height */ max-height: 58px; /* limit the height to avoid long text increasing the height */ } ``` ## PagingDisabled since 8.0 Once the `pagingDisabled` is set to `true`, users will be blocked from navigating through the pagination. # Selection ## Nonselectable Tags since 5.0 By default, when a user clicks on an HTML