List component
Overview
The List component is the primary way to display a collection of items in a Purple Experience view. It fetches data from a Data Sources, renders each item using a child component template, and optionally tracks which item is currently selected via a URL query parameter.
Templates
The template property controls the layout of the list:
Value | Description |
|---|---|
vertical | Stacked vertically (default) |
horizontal | Scrolls horizontally |
tabs | Renders items as tabs; selection scrolling is disabled for this template |
grouped | Groups items under section headers |
grid | Arranges items in a CSS grid |
Selection
Add a selection object to make a list track which item is currently selected. The selected value is stored as a URL query parameter (or another scope) and is available to child components as $context.selected.
"selection": {
"param": "category",
"init": "FIRST",
"scrollIntoView": { "behavior": "smooth", "block": "nearest" }
}Selection properties
Property | Type | Default | Description |
|---|---|---|---|
param | string | — | Required. URL query parameter that stores the selected value |
paramScope | URL | UserAttribute | URL | Where the selected value is persisted |
init | boolean | 'FIRST' | 'ALL' | false | Pre-select on load: 'FIRST' selects the first item, 'ALL' selects all items, true behaves like 'FIRST' |
multi | boolean | false | Allow multiple items to be selected simultaneously |
ripple | boolean | false | Show a ripple animation on the selected item |
scrollIntoView (PXP 5.4.0 or higher) | ScrollIntoViewOptions | false | { behavior: 'smooth' } | Scroll options when bringing the selected entry into view. Set to false to disable scrolling. Not applied when template is 'tabs'. Behaves like |
confirm | object | — | Show a confirm button |
reset | boolean | string | — | Show a reset button. Use a string to override the button label (default translation key: LIST_ACTION_RESET) |
selectAll | boolean | string | — | Show a "select all" button (default key: LIST_ACTION_SELECT_ALL) |
unSelectAll | boolean | string | — | Show an "unselect all" button (default key: LIST_ACTION_UNSELECT_ALL) |
ScrollIntoViewOptions
These options are passed directly to the browser's scrollIntoView() API when the selected entry needs to be brought into view.
Property | Type | Default | Description |
|---|---|---|---|
behavior | 'auto' | 'smooth' | 'instant' | 'smooth' | Scroll animation style |
block | 'start' | 'center' | 'end' | 'nearest' | — | Vertical alignment of the element after scrolling |
inline | 'start' | 'center' | 'end' | 'nearest' | — | Horizontal alignment of the element after scrolling |
container | 'all' | 'nearest' | — | Which scroll container(s) to scroll |
Disabling scroll on selection
To prevent the view from jumping when a list item is selected - for example when a list is already fully visible - set scrollIntoView to false:
"selection": {
"param": "tab",
"init": "FIRST",
"scrollIntoView": false
}Confirm button
The optional confirm button is shown below the list and triggers an action when clicked. Useful for filter lists where changes should only take effect once the user confirms.
Property | Type | Default | Description |
|---|---|---|---|
message | string | 'LIST_ACTION_CONFIRM' | Button label (translation key or literal string) |
action | EventActionConfig | — | Action to execute when the button is clicked - see Action ConfigurationAction Configuration |