---
title: "list"
description: "Show clickable items in a customizable list."
permalink: /docs/runtime/all-ui-components/list/
---
# list

<RuntimeVersion updatedSince="4.84.0">
Added list controls, pagination, and an empty-state message.
</RuntimeVersion>

## Overview

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

![](./media/spaces-2f9tchlr67elhbojpvhhud-2fuploads-2fifiprkiiuviqn3boboqw-2fscreen-20shot-202022-10-13-20at-2011.18.24-20am-d16fe803.png)

**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>
```

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

<DocsReference href="/docs/runtime/all-ui-components/list/list-item/" />

## Advanced Attributes

### `controls`

<SyntaxCard type={["none", "bottom", "top", "both"]} defaultValue="none" />

<RuntimeVersion since="4.84.0" />

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`

<SyntaxCard type="left-to-right, right-to-left" defaultValue="left-to-right" introduced="4.86.1" />

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

![](./media/spaces-2f9tchlr67elhbojpvhhud-2fuploads-2ffuyet4freg6w9kfyfl71-2fimage-ae1a117e.png)

### `limit`

<SyntaxCard type="integer (minimum 2)" defaultValue="none" introduced="4.84.0" />

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`

<SyntaxCard type="string" defaultValue="unset" introduced="4.84.0" />

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

### `show-pagination`

<SyntaxCard type="boolean" defaultValue="true" introduced="4.89.0" />

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`

<SyntaxCard type="boolean" defaultValue="true" introduced="4.89.0" />

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`

<SyntaxCard defaultValue="unset" />

`init-state` initializes a `list`'s state after the list loads. Return the starting values from a view function using the [state fields](#state); you can supply just the fields you want to initialize.

### `on-state-change`

<SyntaxCard defaultValue="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`

The `$state` parameter contains the current [list state](#state).

`on-state-change` is an event that calls a JS/TS [`$:function`](/docs/get-started/syntax/expressions-and-events/) or [navigation](/docs/runtime/view-navigation/). See more details:

- [Expressions and Events](/docs/get-started/syntax/expressions-and-events/#call-functions-from-events)

### `align-label`

<AttributeReference label="align-label" href="/docs/runtime/common-component-attributes/align-label/" badge="advanced" tone="muted" />

### `label-case`

<AttributeReference label="label-case" href="/docs/runtime/common-component-attributes/label-case/" badge="advanced" tone="muted" />

### `label-color`

<AttributeReference label="label-color" href="/docs/runtime/common-component-attributes/label-color/" badge="advanced" tone="muted" />

### `icon-position`

<AttributeReference label="icon-position" href="/docs/runtime/common-component-attributes/icon-position/" badge="advanced" tone="muted" />

### `id`

<AttributeReference label="id" href="/docs/runtime/common-component-attributes/id/" badge="advanced" tone="muted" />

### `show-if`

<AttributeReference label="show-if" href="/docs/runtime/common-component-attributes/show-if/" badge="advanced" tone="muted" />

### `hide-if`

<AttributeReference label="hide-if" href="/docs/runtime/common-component-attributes/hide-if/" badge="advanced" tone="muted" />

## Common Attributes

### `border-radius`

<AttributeReference label="border-radius" href="/docs/runtime/common-component-attributes/border-radius/" badge="new" sinceVersion="5.1.0" />

### `label`

<AttributeReference label="label" href="/docs/runtime/common-component-attributes/label/" />

## State

The `on-state-change` handler receives the current state as `$state`. Use `init-state` to supply initial values or `component.list({ id: 'my-list' }).setState(...)` to update them after loading. For programmatic updates, give the list a matching XML `id`.

```typescript
interface ListState {
  /**
   * The global search applied on the list
   */
  search?: string;
  /**
   * Current page size
   */
  limit?: number;
  /**
   * Current page of the list, starts at 1
   */
  page?: number;
  /**
   * The index of the currently selected item (1-based)
   */
  selectedItem?: number;
}
```

The list supports these fields in both `init-state` and `setState()`. Page numbers and selected-item indexes start at 1.

<DocsReference href="/docs/guides/common-app-patterns/managing-component-state/" />

## Component Methods

The following component methods are available when an [`id`](/docs/runtime/common-component-attributes/id/) is assigned to the component and `component.list({id:'my-id'})` is called from JS/TS:

### `setState`

Set or update the [state](#state) of the `list`. For example, `component.list({ id: 'my-list' }).setState({ page: 1, search: '' })` resets pagination and search.

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

**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>
```

**main.js**

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

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

**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>
```

**main.js**

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

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