ptc-list

Visual

Overview

A ptcs-list displays a list. Each list item can have a main "value label" and an optional "meta label" that is displayed below the value. The list supports both single and multiple selection mode. You can filter the list items.

Usage Examples

Basic Usage

<ptcs-list items="[[items]]"></ptcs-list>

Multi selection list

<ptcs-list select-mode="multiple" items="[[items]]"></ptcs-list>

List using a filter

<ptcs-list filter items="[[items]]"></ptcs-list>

Component API

Properties

Property	Type	Description
alignment	String	Controls the alignment of items within the list. You can set it to 'right', 'left', or 'center'. Set to 'left' by default.
allowNoItemSelection	Boolean	Disables or enables the clear selection button for single items
autoSelectFirstRow	Boolean	Automatic select first item when items list is changed (true). No pre-defined selection otherwise
clearSelectionLabel	String	The text to show in the item used to clear selection in single selection mode (when allowNoItemSelection is true)
disabled	Boolean	Disables the list
filter	Boolean	Displays a text-field box that filters the list
hintText	String	The text for the "clear selection" label in single selection mode
itemMeta	Object	Determines the item type. You can set it to text, link, image, and checkbox.
items	Array	A JavaScript array that contains the list data
label	String	An optional label that appears above the list
labelAlignment	String	Controls the alignment of items within the list. You can set it to 'right', 'left', or 'center'. Set to 'left' by default.
labelType	String	A variant to use for the list label. Default is 'label'. You can set it to 'header', 'sub-header', and 'body'.
selectAllLabel	String	The text to display for the item used to select all items in the list. The item is displayed at the top of the list when no items are selected in multiple selection mode. Default value: "Select All"
clearSelectedItemsLabel	String	The text to display for the item used to clear all selections in the list. The item is displayed at the top of the list when one or more items are selected in multiple selection mode. Default value: "Clear Selected Items"
metaSelector	Any	The same as selector but selects the meta string instead. If metaSelector has false data, the meta string is not displayed.
multiLine	Boolean	Determines whether list items can be displayed across multiple lines.
multiSelect	Boolean	Enables multiple item selection
rowHeight	String	Sets the row height
selected	Number	If selectMode = "single" then selected contains the selected item, if any.
selectedIndexes	Array	An array with the indexes of the selected items
selectedItems	Array	An array with the selected items
selectedValue	Object	If selectMode = "single" then selectedValue contains the selected item's value (according to valueSelector), if any.
selector	Any	Selects a string from each item in items to be displayed as the list item label. If unassigned, items should be an array of strings. If a string then items should be an array of objects, where the selector specifies the (string) property to display. If a function, then the function is called with each item and should return a string that represents the item.
treatValueAsString	Boolean	Deprecated. Returns selectedValue as a string. Disabling the property returns the original object.
returnOriginalValue	Boolean	Returns selectedValue in the original object format when set to true and as a string when set to false.
valueSelector	Any	Selects a string from each item in items to display as the list item value. If unassigned, uses selector instead. If a string then items should be an array of objects, where selector specifies the (string) property to display. If a function, then the function is called with each item and should return a string that represents the item.
ownerTooltip	String	A tooltip from a list owner (a component that uses ptcs-list, e.g. ptcs-dropdown) to be shown as part of list item truncation overflow tooltip
ownerTooltipIcon	String	Icon for the owner tooltip
extraValidation	Function	Custom validation function to complement the component's client-side validation logic. This is invoked with the list component itself as parameter, so that it can use any ptcs-list property for custom validation. Can return true (= valid), false (= invalid), or undefined (ignore validation)
externalValidity	String	List validity as determined externally (server-side). Value: undefined, "unvalidated", "invalid", or "valid"
hideValidationCriteria	Boolean	Don't show validation criteria in unvalidated state?
hideValidationError	Boolean	Don't show validation error state?
hideValidationSuccess	Boolean	Don't show validation success state?
required	Boolean	Validation criterion: Must the list have a selection?
validationCriteria	String	The validation details message
validationCriteriaIcon	String	Icon for criteria state (unvalidated). Default: cds:icon_info
validationErrorIcon	String	Icon for error state (invalid). Default: cds:icon_error
validationMessage	String	The validation (title) message
validationSuccessDetails	String	The validation success details message
validationSuccessIcon	String	Icon for success state (valid). Default: cds:icon_success
validationSuccessMessage	String	The validation success (title) message. Default: "Success"

Events

Name	Data	Description
DoubleClicked	{ index of clicked item }	Triggered whenever double-click event occurs on any item

Methods

No methods

Styling

Parts

Part	Description
root	The container for list
label	An optional list label above the list
list-container	The list body container (everything but the label)
filter	The filter text-field
filter-field	The filter text-field
multi-select	the container for the link control that allows the whole list to be selected or unselected in multi-select mode
link	The select or un-select all link
list-item	A list item in the list
item-checkbox	The checkbox in multiple selection mode
item-value	The value label in the list item
item-meta	The meta label in the list item