---
title: List component
slug: experience/list-component
docTags: 
createdAt: 2026-04-13T14:50:30.859Z
---

## 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](https://app.archbee.com/docs/qtjKveW7g556Yo3qfoyAY/fuMBUaBWeON_OTO5wfevf), 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`.

```json
"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<br />[scrollIntoView API](https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView) |
| `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`:

```json
"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 Configuration](docId\:oAFVNh5BJFZvVgT6G-YRd)  |