---
title: "object-list"
description: "Overview"
permalink: /docs/build/ui-components/all-ui-components/object-list/
---
# object-list

## Overview

An `object-list` displays data from objects (from [database query](/docs/get-started/journeyapps-fundamentals/accessing-the-database/querying-db-objects/) or [array](/docs/get-started/journeyapps-fundamentals/accessing-the-database/querying-db-objects/#arrays)) in a visible way. It differs in this regard from the [`object-dropdown`](/docs/build/ui-components/all-ui-components/object-dropdown/) component, the latter needs to be selected by a user to display the data and allow them to select an option.

An `object-list` can be customized in 3 ways:

* [Non-Selectable](#non-selectable-object-list)
* [Selectable](#selectable-object-list)
* [Clickable](#clickable-object-list)

### Initialization of Data for `object-list`

All `object-list` variations (see below) use a [DB query](/docs/get-started/journeyapps-fundamentals/accessing-the-database/querying-db-objects/) or [array](/docs/get-started/journeyapps-fundamentals/accessing-the-database/querying-db-objects/#arrays) to determine which objects to display.

**main.view\.xml**

```xml
<var name="all_items" type="query:item" />
<!-- OR -->
<var name="all_items_array" type="array:item" />
```

**main.js**

```javascript
function init() {
     view.all_items = DB.item.all();
     // OR
     view.all_items_array = DB.item.all().toArray();
}
```

### Non-Selectable `object-list`

This list can be used for display purposes only and doesn't allow the user to select anything.

**main.view\.xml**

```xml
<var name="all_items" type="query:item" />

<object-list query="all_items" label="All Items:" empty-message="There are no items" />
```

![](./media/spaces-2f9tchlr67elhbojpvhhud-2fuploads-2fgit-blob-b35b83eb92ec7eae5c5a708f67c8a8408489127c-2fobject-list-non-selectable-example-9348aa67.png)

### Selectable `object-list`

This list allows the user to select one of the objects in it, which is then highlighted. The selected object is stored in a specified variable (specified using `bind=""` see *Configuration* below).

A Selectable List is typically used in conjunction with a button — The user selects an object in the list, and then clicks a button to take an action — for example, calling a JavaScript/TypeScript function which does something with the object that the user selected (referencing the variable in which the selected object is stored), or follow a link (passing the selected object as a parameter to the next view)

**main.view\.xml**

```xml
<var name="all_items" type="query:item" />
<var name="selected_item" type="item" />

<object-list query="all_items" bind="selected_item" label="All Items:" empty-message="There are no items" />
```

![](./media/spaces-2f9tchlr67elhbojpvhhud-2fuploads-2fgit-blob-22322155b8a1a4485cc380ad58f639f8a50f6ddf-2fobject-list-selectable-example-d2f5ac52.png)

### Clickable `object-list`

This list allows the user to tap or click on a particular object, a specified JavaScript/TypeScript function is then called, and the object that the user selected is passed as an argument to the JavaScript/TypeScript function.

An arrow on the right side of the `object-list` items hints to the user that the list items are clickable.

The JavaScript/TypeScript function that is called when the user taps on a list item is typically used to follow a link to a next screen — Therefore, a Clickable Regular List is used for similar cases as a Selectable Regular List, but it provides a better user experience because it requires less scrolling and tapping by the user.

**main.view\.xml**

```xml
<var name="all_items" type="query:item" />

<object-list query="all_items" label="All Items:" empty-message="There are no items">
  <action on-press="selectItem($selection)" />
</object-list>
```

Note that a function call of your choosing is specified at `on-press=""`, which you then need to define in the view's JavaScript/TypeScript. The object that the user selected can be passed as an argument to this JavaScript/TypeScript function (`clickedItem` in the example below) by using the special `$selection` variable.

The most common use case of a clickable list is to call a navigation [link](/docs/get-started/journeyapps-fundamentals/view-navigation/) when the user clicks on an item, and pass the clicked object as an argument to the link — which we show in this example below.

**main.js**

```javascript
function selectItem(clickedItem) {
    navigate.link("view_item", clickedItem);
}
```

We can also call the link directly from the [`on-press`](/docs/build/ui-components/all-ui-components/action/#on-press) attribute:

**main.view\.xml**

```xml
<action on-press="navigate.link('view_item', $selection)" />
```

![](./media/spaces-2f9tchlr67elhbojpvhhud-2fuploads-2fgit-blob-c8eb7191694b31e85245e4d06b9bf081751d8562-2fobject-list-clickable-example-072bd990.png)

## Standard Attributes

### query

<SyntaxCard defaultValue={"unset"} required />

`query` contains the name of the query or array variable to populate the objects in the `object-list`.

```xml
<var name="all_items" type="query:item" />
<var name="selected_item" type="item" />

<object-list query="all_items" bind="selected_item" label="All Items:" empty-message="There are no items" />
```

## Advanced Attributes

### `display`

<SyntaxCard type={"string"} defaultValue={"The <display/> tag of the object as defined in the app's data model"} />

Specifies the display value of each option in the `object-list`. Can be a static string, a [format string](/docs/app-features/xml-format-strings/) or a [JS/TS function](/docs/app-features/calling-js-functions-from-xml/).

**schema.xml**

```xml
<model name="country" label="Country">
    <field name="name" label="Name" type="text:name"/>
    <field name="population" label="Population" type="integer"/>
    
    <display>{name}</display>
</model>
```

**main.view\.xml**

```xml
<!-- Here the display value for each option is the country's name and population, separated by a "-" -->
<object-list label="Country of residence" display="{name} - {population}" query="countries" bind="selected_country" required="true" />
```

### `empty-message`

<SyntaxCard type={"string (static text, format string, or JS/TS function result)"} defaultValue={"\"No items to display\""} />

Text that is displayed if no options are available to list once the user opens the `object-list`.

### `show-if`

<AttributeReference label="show-if" href="/docs/build/ui-components/common-attributes/show-if/" badge="advanced" tone="muted" />

### `hide-if`

<AttributeReference label="hide-if" href="/docs/build/ui-components/common-attributes/hide-if/" badge="advanced" tone="muted" />

## Common Attributes

### `bind`

<Info>

`bind` only applies to [selectable](#selectable-object-list) `object-list`s.

</Info>

<AttributeReference label="bind" href="/docs/build/ui-components/common-attributes/bind/" />

### `label`

<AttributeReference label="label" href="/docs/build/ui-components/common-attributes/label/" />

### `required`

<Info>

`required` only applies to [selectable](#selectable-object-list) `object-list`s.

</Info>

<AttributeReference label="required" href="/docs/build/ui-components/common-attributes/required/" />