Class “ItemPicker”

Object > NativeObject > Widget > Picker > ItemPicker

Type: ItemPicker<ItemType> extends Picker
Generics: ItemType: any
Constructor: public
Singleton: No
Module: tabris-decorators
Direct subclasses: None
JSX Support: Element: <ItemPicker/>
Parent Elements: <Canvas/>, <Cell/>, <Composite/>, <Page/>, <RefreshComposite/>, <Row/>, <ScrollView/>, <Stack/>, <Tab/>
Child Elements: Not Supported
Element content sets: items

ItemPicker is a high-level extension of the low-level Picker widget. It provides additional API to make usage more convenient, but does not add any new features.

In contrast to Picker, it has an items property (taking either an array or a List) and does not necessarily require a callback to determine the text of a list entry. Instead the items can be strings themselves, implement a toString() method, or provide a specific property containing the text. This item property may be given via textSource.

ListView is not exported by the tabris module, but by tabris-decorators, which needs to be installed separately.



  <ItemPicker stretchX textSource='name'>
      {name: 'Paul', id: 'person#101'},
      {name: 'Amanda', id: 'person#102'},
      {name: 'Jessica', id: 'person#103'}

See also:

JS Example with various item types
JSX Example with various item types (JSX variant)
JSX Data Binding Example
TSX Example with various item types (TypeScript/JSX variant)
TSX Data Binding Example (TypeScript variant)


new ItemPicker(properties?)

Parameter Type Description
properties Properties<ItemPicker> Sets all key-value pairs in the properties object as widget properties. Optional.



List or Array containing the items that can be selected. If a List is used any changes to the list (items added/removed/replaced) are applied to the ItemPicker automatically.

When items changes - either by modifying List or setting a new Array - the selection state will be preserved if the index currently selected item remains unchanged.

Items can also be provided as an array literal (within curly braces) or plain text with the <ItemPicker> JSX element. If text is given it will be interpreted as a comma separated list.

Type: List<ItemType> | ItemType[]
Default: null
Settable: Yes
Change Event: itemsChanged
JSX Content Type: List<ItemType> | ItemType[]

When using ItemPicker as an JSX element the elements content value is mapped to this property.


The currently selected item. Corresponds to the itemIndex property. The value is adjusted automatically if items is manipulated. In this case a selectionChanged event is fired, but no select event.

Type: ItemType
Settable: Yes
Change Event: selectionChanged


Controls how the text representing an item is determined.

If this property is not set, the item is simply stringified. This works best when the item is a string already or implements a toString() method.

If the value is a string, it is interpreted as the name of a property of the item object. That property is used as the text. The string can also point to a sub-property, like a data binding path. If the property is @property-decorated, changes will be applied automatically.

Lastly, a path string can be combined with a converter function in a plain object.

Type: null
| string
| {path: string, converter: Function}
Default: null
Settable: Yes
Change Event: textSourceChanged



Fired when an item was selected by the user. Same as the select event, except that it provides not just the item index, but also the item and the item text.

EventObject Type: ItemPickerItemSelectEvent<ItemPicker>

Property Type Description
item ItemType  
itemIndex number  
itemText string  

Change Events


Fired when the items property has changed.

EventObject Type: PropertyChangedEvent<ItemPicker, List | Array>

Property Type Description
value List<ItemType> | ItemType[] The new value of items.


Fired when the selection property has changed.

EventObject Type: PropertyChangedEvent<ItemPicker, ItemType>

Property Type Description
value ItemType The new value of selection.


Fired when the textSource property has changed.

EventObject Type: PropertyChangedEvent<ItemPicker, null
| string
| Object>

Property Type Description
value null
| string
| {path: string, converter: Function}
The new value of textSource.