List

Overview

• The Dynamic List displays a scrollable or paginated list of items in a section.
• It supports dynamic data loading and virtualization for performance.
• It renders large datasets efficiently.
• It offers flexible layout and can render custom child elements per item.
• It is customizable through data source options and visual properties.

Specs

Tokens

Token	Description
displayName	Display name of the component shown in the structure panel.
id	Unique identifier for the component; also useful for programmatic access in testing or custom code.
itemSize	Height of each list item in pixels.
autoHeight	Automatically adjusts list height to the number of visible elements.
numberOfVisibleListElements	Number of items visible when autoHeight is enabled.
dataSourceId	ID of the data source to fetch data from.
dataSourcePath	**JSON path to extract list data from the response.
getEntityCollectionHttpRequestParametersMap	HTTP parameters map for collection requests (QUERY, PATH, BODY).
keyExpression	Field used as a unique key for each list item.
enablePagination	Enables server-side pagination for large datasets.
pageSize	Number of items to load per page.
elements	Child dynamic elements rendered for each list item.
visibilityPolicySetId	Determines component visibility based on user permissions and policy sets (e.g., restrict the Dynamic List to a specific team policy).
dataTestId	Testing hook ID for automated testing to reliably identify the Dynamic List.
enableAsHotspot	Enables the component as a guided tour hotspot for onboarding.
paddingClass	CSS utility class that controls padding around the Dynamic List (e.g., p-4).

Structure

• elements - Contains child dynamic elements to be rendered for each list item. This allows for flexible layouts and embedding of other dynamic components within each list entry.

(Configured in General Properties)

• displayName - Sets the display name of the component, shown in the structure panel.

Datasource

(Configured in Data Source Properties)

• dataSourcePath - Defines a JSON path expression to extract the list data from the API response. This is useful when the data is nested within the response object.
  • getEntityCollectionHttpRequestParametersMap - Configures HTTP request parameters for fetching data from the data source. Allows mapping of query, path, or body parameters as needed by the backend API.
• dataSourceId - Specifies the ID of the data source from which the list fetches its data. This should match a configured data source in your system.
• keyExpression - Defines the field used as a unique key for each list item. This improves rendering performance and ensures correct item tracking.

Styling

(Configured in Visual Properties)

• itemSize - Sets the height (in pixels) of each list item; for example, setting itemSize: 80 renders each list item at 80px and changes the vertical space each item occupies.
• autoHeight - When enabled (e.g., autoHeight: true), the list automatically adjusts its height based on the number of visible elements, shrinking or growing to fit its content in flexible layouts.
• numberOfVisibleListElements - Specifies how many list items should be visible when autoHeight is enabled; for instance, numberOfVisibleListElements: 5 with itemSize: 100 results in a component height of 500px.

(Configured in Layout)

• paddingClass - Configures the padding around the component using CSS utility classes; for example, p-4 adds substantial padding on all sides of the Dynamic List component.

(Configured in Data Source Properties)

• enablePagination - Enables server-side pagination for large datasets; when true (e.g., enablePagination: true), the list loads data page by page as the user scrolls rather than all at once.
• pageSize - Sets the number of items to load per page when pagination is enabled; for example, pageSize: 25 loads 25 items per page.

Tests

(Configured in Testing Hooks)

• id - Specifies a unique identifier for the component, useful for programmatic access in testing or custom code.
• dataTestId - Sets a testing hook ID for automated testing, allowing test scripts to reliably identify this Dynamic List component.
• enableAsHotspot - Enables the component as a guided tour hotspot. When enabled, this Dynamic List can be highlighted during onboarding tours.

Authorization

(Configured in Authorization)

• visibilityPolicySetId - Determines the visibility of the component based on user permissions and policy sets. For example, setting it to "marketingTeamPolicy" restricts the Dynamic List to users with marketing team privileges.

Visibility

(Configured in Visibility)

• Defines conditions under which the Dynamic List is displayed. This allows for context-aware visibility, showing the list only when certain conditions are met (e.g., when a specific data set is selected).

Guidelines

Usage

• Render large datasets efficiently with incremental loading — enable enablePagination and choose an appropriate pageSize; keep identity stable via keyExpression.
• Compose each row’s UI using child elements.

Sizing & Layout

• Define a single row height with itemSize.
• Prefer a fixed scroll viewport by leaving autoHeight off when continuous scrolling within the section is desired.
• Add outer spacing with paddingClass.

Interactions & Events

• The list exposes no built-in events; implement interactivity within per-item elements.
• Provide reliable automation handles with id and dataTestId.

Visibility & Authorization

• Gate visibility using visibilityPolicySetId.

Content & Localization

• Use displayName only for authoring clarity in the structure panel.
• Place all user-facing copy inside per-item elements (the Dynamic List has no *Translations tokens).

Dos & Don’ts

Do	Don’t	Article setting(s)
Use enablePagination: true with a tuned pageSize for large datasets.	Load entire collections at once.	enablePagination, pageSize
Define a unique keyExpression for each item.	Rely on array index as a key.	keyExpression
Set a single consistent item height.	Mix variable heights without adjusting tokens.	itemSize
Use autoHeight: true with numberOfVisibleListElements to size the list precisely.	Hard-code heights that don’t match row height × count.	autoHeight, numberOfVisibleListElements, itemSize
Build each row’s UI via child elements.	Attempt to place per-item content outside the list.	elements
Reserve space around the list for readability.	Let list content touch container edges.	paddingClass
Hide content from unauthorized users.	Show restricted data and hope downstream logic blocks it.	visibilityPolicySetId
Opt into onboarding highlights when needed.	Simulate highlights with custom overlays.	enableAsHotspot

Accessibility

• Provide semantics through row content: add accessible text/roles within per-item elements (the list itself adds none).
• Prevent disruptive layout shifts by aligning itemSize with autoHeight/numberOfVisibleListElements when auto-sizing.
• Expose stable hooks for accessibility automation with dataTestId and id.
• On very large datasets, reduce DOM size for assistive tech by using enablePagination with a reasonable pageSize.
• Maintain item identity during updates with an immutable keyExpression.
• Keep essential, concise text per row inside elements; don’t rely on displayName for users.
• Use paddingClass to preserve readable spacing around content.

Datasource Requirements

Data Example

The list expects an array of objects, each representing a list item. If using pagination, the response should be a paginable object with a content array.

Array of items:

[
  { "userId": 1, "name": "Alice" },
  { "userId": 2, "name": "Bob" }
]

Paginable response:

{
  "content": [
    { "userId": 1, "name": "Alice" },
    { "userId": 2, "name": "Bob" }
  ],
  "totalElements": 100,
  "totalPages": 10,
  "number": 0,
  "size": 10
}