list
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.
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

main.view.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
).See the
list-item
documentation for further details:Optional
Type:
none
| bottom
| top
| both
Default:
none
Version compatibility
controls
was introduced in version 4.84.0 of the JourneyApps Runtime.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
.<list controls="top">
<list-item>
...
</list-item>
</list>
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" |
Version compatibility
content-direction
was introduced in version 4.86.1 of the JourneyApps Runtime.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.
<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>

Version compatibility
label-case
was introduced in version 4.86.1 of the JourneyApps Runtime.Version compatibility
label-color
was introduced in version 4.86.1 of the JourneyApps Runtime.Version compatibility
limit
was introduced in version 4.84.0 of the JourneyApps Runtime.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.<list controls="top" limit="8">
<list-item>
...
</list-item>
</list>
Version compatibility
empty-message
was introduced in version 4.84.0 of the JourneyApps Runtime.Optional
Type:
string
Default: unset
Text that is displayed inside the
list
when it is empty.<list label="Technicians assigned to the job" empty-message="No technicians are currently assigned">
<list-item query="assigned_technicians">
...
</list-item>
</list>
Version compatibility
icon-position
was introduced in version 4.86.1 of the JourneyApps Runtime.Note
icon-position
specifies the icon
position for all list-item
s in the list, whether the icon
was defined per its shorthand version or longhand version.Version compatibility
show-pagination
was introduced in version 4.89.0 of the JourneyApps Runtime.Optional
Type:
boolean
Default:
true
In a paginated
list
, and when 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.Version compatibility
show-search
was introduced in version 4.89.0 of the JourneyApps Runtime.Optional
Type:
boolean
Default:
true
When
controls
are shown, the show-search
attribute can be used to show or hide the search box independent of the pagination controls.The following component methods are available when an
id
is assigned to the component and component.list({id:'my-id'})
is called from JS/TS:Programmatically clears the search value from the search box.
Programmatically select the next page in a paginated
list
.Programmatically select the previous page in a paginated
list
.Programmatically scroll until the
list
is visible in the view.Select a
list-item
from the list
by its header text. This will trigger the list-item
's on-press
event.main.view.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
function select() {
component.list({id: 'my-list'}).selectItem('Manage Assets');
}
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
<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
function select() {
component.list({id: 'my-list'}).selectItemByIndex(1);
// Selects the "Manage Assets" list-item
}
Programmatically select the a page in a paginated
list
by its page number.Programmatically enter a search value and triggers a search of the
list
.Last modified 1mo ago