From Documentation


  • Available for ZK:
  • ee.png

Since 9.0.0


A dropdown list that allows users to search and select items. Since it contains a separate search field (unlike Combobox), it can avoid end-users from inputting a non-existed item.



ListModel model = new ListModelArray(new String[] {
  "North America", "South America", "Europe", "Asia", "Africa", "Oceania", "Antarctica"
<searchbox model="${model}" placeholder="An unknown place" autoclose="true">
   <template name="model">
       <i class="z-icon-globe"></i> ${each}

Render HTML Fragment

This component's default ItemRenderer directly renders a model's data into an HTML snippet, hence if your model data contains those characters that need to be escaped like < > &, you need to escape by yourself.

If you want to render different HTML elements for each item on your own, see ItemRenderer.


The item renderer is used to render each item's HTML content. See ZK Developer's Reference/MVC/View/Renderer/Item Renderer.

If you just want to customize the rendered text, see Model Template.

Keyboard Navigation Searchbox

  • UP or DOWN to pop up the list if being focused.
  • ESC to close the list.
  • UP, DOWN, HOME, END, PAGE UP and PAGE DOWN to change the selection of the item from the list.
  • ENTER to confirm the change of selection.
  • Since 9.5.0 DELETE or BACKSPACE to clear the selection.



Sets whether to automatically close the list if a user selected any item. The default value is false. It means even if the user selected an item, the list still remains open. You might want to set it as true in single selection mode (multiple=false).


Sets whether it is disabled. A list can still be opened programmatically by calling open() even if the component is in the disabled state.


By implementing your own Converter using the org.zkoss.util.Converter interface, you can generate the label that represents the selected items. The default implementation is joining all the toString() result of items by commas.

Can accept a Class name as a string, in which case an instance of that class will be created automatically, or an object already instantiated.

    <searchbox model="${model}" itemConverter="" />
    <searchbox model="${model}" itemConverter="${myConverterObject}" />


The item renderer is used to render each item's HTML content. See ZK Developer's Reference/MVC/View/Renderer/Item Renderer.

If you just want to customize the rendered text, see Model Template.


Since this component doesn't accept any child, you must specify a ListModel.

If a ListSubModel is provided, all the items will not be rendered to the client directly. Instead, users must type a keyword to search for a subset of the list. It's suitable for a large model.

Note: If you assign a ListModel to a searchbox, you should enable multiple selections with ListModel. Please do not set multiple on searchbox directly. You should set multiple on the model instead.

List Items = new ArrayList();
for (int i = 0; i < 1000; i++) {
	Items.add("data "+i);
ListModelList model = new ListModelList(Items);

<searchbox model="${model}" ... />


Sets whether multiple selections are allowed.


Drops down or closes the list of items.


Sets the placeholder text that is displayed when there's nothing selected.


Sets the placeholder message of the search text field. The default is "Type to search".


Returns the selected item, or null if no item is selected. When multiple is true, it returns the first of the selected items.

Don't use MVVM annotations in both selectedItem and selectedItems at the same time since @save selectedItem will deselect all of the currently selected items first.


Returns all selected items.

Supported Events

Event Type
Event: Event

Notifies one that the model's data has been rendered as components on the server side.

Event: SelectEvent

Represents an event caused by the user that the list selection is changed at the client.

Event: OpenEvent

Denotes that the user has opened or closed a component. Note: unlike onClose, this event is only a notification. The client sends this event after opening or closing the component.

Event: InputEvent

Notifies one that the user is searching by keywords.

Supported Children

* none

Version History

Last Update : 2023/07/26

Version Date Content
9.0.0 September 2019 ZK-4380: Provide a Searchbox component
9.5.0 August 2020 ZK-4497: searchbox: improve clearing selection, key shortcut / clear icon

Last Update : 2023/07/26

Copyright © Potix Corporation. This article is licensed under GNU Free Documentation License.