# list

## Overview

{% hint style="info" %}
**Version compatibility**

`list` was introduced in version **4.29.0** of the JourneyApps Container.

It received several functional updates in version **4.84.0** of the JourneyApps Runtime.
{% endhint %}

The `list` UI component lists clickable items in a more visually prominent and customizable manner than pure text-based lists. `list` is a very versatile UI component and can be applied in many use cases, some common ones include:

* A list of jobs, where each job is color-coded per its status
* A set of photos taken, where the photo is displayed in thumbnail format on the item 
* A set of navigational links
* A list of actions or workflow steps where each action could show a completed state

### Basic Structure

<figure><img src="https://2865107717-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9TCHLR67eLHBOjPvHhud%2Fuploads%2FIfiprkiiUviqN3bObOQw%2FScreen%20Shot%202022-10-13%20at%2011.18.24%20AM.png?alt=media&#x26;token=999fdb94-7fb5-427b-8060-b288265803f1" alt=""><figcaption></figcaption></figure>

{% code title="main.view\.xml" %}

```xml
<var name="tickets" type="query:ticket" />

<list empty-message="No recent field tickets" controls="top" limit="5">
    <list-item query="tickets">
        <pills>
            <pill label="{date}" color="{rig.color}" />
        </pills>
        <header>{customer}</header> 
        <content>Pad: {pad_name} | Well: {well_name} | Rig: {rig}</content> 
        <footer>Total: ${ticket_total}</footer> 
        <accent label="Ticket Status: {status}" color="$:getStatusColor($object)" />
        <action on-press="selectTicket($selection)" />
    </list-item> 
</list>
```

{% endcode %}

`list` contains one or many `list-item` elements, which are either static (for basic usage) or dynamic (will repeat itself for each item in a `query`).

See the `list-item` documentation for further details:

{% content-ref url="list/list-item" %}
[list-item](https://docs.journeyapps.com/reference/build/ui-components/all-ui-components/list/list-item)
{% endcontent-ref %}

## Standard Attributes

### `label`

{% content-ref url="../xml-fields/label" %}
[label](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/label)
{% endcontent-ref %}

## Advanced Attributes

### `align-label`

{% content-ref url="../xml-fields/align-label" %}
[align-label](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/align-label)
{% endcontent-ref %}

### `controls`

**Optional**

**Type**: `none` | `bottom` | `top` | `both`

**Default**: `none`

{% hint style="info" %}
Version compatibility

`controls` was introduced in version **4.84.0** of the JourneyApps Runtime.
{% endhint %}

Controls allow a user to search a `list` and, if the `list` is paginated, to navigate to the next, previous or a specific page. Controls are hidden by default, but can be positioned at the bottom and/or top of a `list`.

```xml
<list controls="top">
    <list-item>
        ...
    </list-item>
</list>
```

#### Positioning

| Parameter | Description                                      | Example             |
| --------- | ------------------------------------------------ | ------------------- |
| `top`     | Positions controls at the top of the list        | `controls="top"`    |
| `both`    | Positions controls at top AND bottom of the list | `controls="both"`   |
| `bottom`  | Positions controls at the bottom of the list     | `controls="bottom"` |
| `none`    | No controls                                      | `controls="none"`   |

### `content-direction`

{% hint style="info" %}
**Version compatibility**

`content-direction` was introduced in version **4.86.1** of the JourneyApps Runtime.
{% endhint %}

**Optional**

**Type**: `left-to-right`, `right-to-left`

**Default**: `left-to-right`

Specify the direction of the component’s content. Typically this mirrors all elements within the component.

```xml
<columns>
    <column>
        <info>content-direction="left-to-right"</info>
        <list content-direction="left-to-right">
            <list-item icon="fa-plus-circle">
                <pills>
                    <pill label="Newly created users: 4" color="positive" />
                </pills>
                <header>Add User</header>
                <content>Add a new user to the selected district</content>
            </list-item>
        </list>  
    </column>
    <column>
        <info>content-direction="right-to-left"</info>
        <list content-direction="right-to-left">
            <list-item icon="fa-plus-circle">
                <pills>
                    <pill label="Newly created users: 4" color="positive" />
                </pills>
                <header>Add User</header>
                <content>Add a new user to the selected district</content>
            </list-item>
        </list> 
    </column>
</columns>
```

<figure><img src="https://2865107717-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9TCHLR67eLHBOjPvHhud%2Fuploads%2FfuYEt4fREg6w9kFyFl71%2Fimage.png?alt=media&#x26;token=8da876b7-43f2-4fa4-9f83-48ac22e5ef3b" alt=""><figcaption></figcaption></figure>

### `label-case`

{% hint style="info" %}
**Version compatibility**

`label-case` was introduced in version **4.86.1** of the JourneyApps Runtime.
{% endhint %}

{% content-ref url="../xml-fields/label-case" %}
[label-case](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/label-case)
{% endcontent-ref %}

### `label-color`

{% hint style="info" %}
**Version compatibility**

`label-color` was introduced in version **4.86.1** of the JourneyApps Runtime.
{% endhint %}

{% content-ref url="../xml-fields/label-color" %}
[label-color](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/label-color)
{% endcontent-ref %}

### `limit`

{% hint style="info" %}
**Version compatibility**

`limit` was introduced in version **4.84.0** of the JourneyApps Runtime.
{% endhint %}

**Optional**

**Type**: `integer` (minimum 2)

**Default**: none

The limit specifies the maximum number of `list-item`s shown on a single page in a `list`. Once a `limit` is defined, the `list` becomes paginated and automatically computes how many pages there will be based on the total amount of items available from the `query` attribute.

**Tip:** When setting a `limit` ensure you also set the `controls` attribute. This will allow users to paginate and search as necessary.

```xml
<list controls="top" limit="8">
    <list-item>
        ...
    </list-item>
</list>
```

### `empty-message`

{% hint style="info" %}
**Version compatibility**

`empty-message` was introduced in version **4.84.0** of the JourneyApps Runtime.
{% endhint %}

**Optional**

**Type**: `string`

**Default**: unset

Text that is displayed inside the `list` when it is empty.

```xml
<list label="Technicians assigned to the job" empty-message="No technicians are currently assigned">
    <list-item query="assigned_technicians">
        ...
    </list-item>
</list>
```

### `icon-position`

{% hint style="info" %}
**Version compatibility**

`icon-position` was introduced in version **4.86.1** of the JourneyApps Runtime.
{% endhint %}

{% hint style="info" %}
**Note**

`icon-position` specifies the `icon` position for all `list-item`s in the list, whether the `icon` was defined per its [shorthand version](https://docs.journeyapps.com/reference/build/ui-components/all-ui-components/list-item#icon) or [longhand version](https://docs.journeyapps.com/reference/build/ui-components/all-ui-components/list-item/asset#icon).
{% endhint %}

{% content-ref url="../xml-fields/icon-position" %}
[icon-position](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/icon-position)
{% endcontent-ref %}

### `id`

{% content-ref url="../xml-fields/id" %}
[id](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/id)
{% endcontent-ref %}

### `show-if` and `hide-if`

{% content-ref url="../xml-fields/show-if" %}
[show-if](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/show-if)
{% endcontent-ref %}

{% content-ref url="../xml-fields/hide-if" %}
[hide-if](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/hide-if)
{% endcontent-ref %}

### `show-pagination`

{% hint style="info" %}
**Version compatibility**

`show-pagination` was introduced in version **4.89.0** of the JourneyApps Runtime.
{% endhint %}

**Optional**

**Type**: `boolean`

**Default**: `true`

In a paginated `list`, and when [`controls`](#controls) are shown, the `show-pagination` attribute can be used to show or hide the pagination controls. This may be useful for lists that only have a single page.

### `show-search`

{% hint style="info" %}
**Version compatibility**

`show-search` was introduced in version **4.89.0** of the JourneyApps Runtime.
{% endhint %}

**Optional**

**Type**: `boolean`

**Default**: `true`

When [`controls`](#controls) are shown, the `show-search` attribute can be used to show or hide the search box independent of the pagination controls.

### `init-state`&#x20;

**Optional**

**Default**: unset

`init-state` initializes an `list`'s state after the list is loaded using a similar structure as [`on-state-change`](#on-state-change).&#x20;

### `on-state-change`

**Optional**

**Default**: unset

**Triggered when**: the state of the `list` is changed due to a UI interaction such as changing to the next page.

**Event parameters**: `$state`

**Return value**: See more information in the guide on list [state](https://docs.journeyapps.com/reference/build/managing-component-state#list).

`on-state-change` is an event that calls a JS/TS [`$:function`](https://docs.journeyapps.com/reference/app-features/calling-js-functions-from-xml) or [navigation](https://docs.journeyapps.com/reference/get-started/journeyapps-fundamentals/view-navigation). See more details:

{% content-ref url="../js-ts-events" %}
[js-ts-events](https://docs.journeyapps.com/reference/build/ui-components/js-ts-events)
{% endcontent-ref %}

## Component Methods

The following component methods are available when an [`id`](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/id) is assigned to the component and `component.list({id:'my-id'})` is called from JS/TS:

### `setState`

Set or update the state of the `list`. See more information in [this guide](https://docs.journeyapps.com/reference/build/managing-component-state#changing-the-state-from-javascript-typescript).

### `clearSearch`

Programmatically clears the search value from the search box.

### `nextPage`

Programmatically select the next page in a paginated `list`.

### `previousPage`

Programmatically select the previous page in a paginated `list`.

### `scrollIntoView`

Programmatically scroll until the `list` is visible in the view.

### `selectItem`

Select a `list-item` from the `list` by its header text. This will trigger the `list-item`'s `on-press` event.

{% code title="main.view\.xml" %}

```xml
<list id="my-list">
    <list-item>
        <header>Manage Assets</header>
        <action on-press="$:manageAssets()" />
    </list-item>
    <list-item>
        <header>Manage Categories</header>
        <action on-press="$:manageCategories()" />
    </list-item>        
</list>
```

{% endcode %}

{% code title="main.js" %}

```javascript
function select() {
    component.list({id: 'my-list'}).selectItem('Manage Assets');
}
```

{% endcode %}

### `selectItemByIndex`

Select a `list-item` from the `list` by its index. This will trigger the `list-item`'s `on-press` event. **Note**: Indexes begin at 1.

{% code title="main.view\.xml" %}

```xml
<list id="my-list">
    <list-item>
        <header>Manage Assets</header>
        <action on-press="$:manageAssets()" />
    </list-item>
    <list-item>
        <header>Manage Categories</header>
        <action on-press="$:manageCategories()" />
    </list-item>        
</list>
```

{% endcode %}

{% code title="main.js" %}

```javascript
function select() {
    component.list({id: 'my-list'}).selectItemByIndex(1);
    // Selects the "Manage Assets" list-item
}
```

{% endcode %}

### `selectPage`

Programmatically select the a page in a paginated `list` by its page number.

### `setSearch`

Programmatically enter a search value and triggers a search of the `list`.