# 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`.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.journeyapps.com/reference/build/ui-components/all-ui-components/list.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.