PickList

PickList is used to reorder items between different lists.

Import #


import { PickListModule } from 'primeng/picklist';

Basic #

PickList is used as a controlled input with source and target properties. Content of a list item needs to be defined with the pTemplate property that receives an object in the list as parameter.

Available

Selected



<p-pickList [source]="sourceProducts" [target]="targetProducts" sourceHeader="Available" targetHeader="Selected" [dragdrop]="true" [responsive]="true" 
    [sourceStyle]="{ height: '30rem' }" [targetStyle]="{ height: '30rem' }" breakpoint="1400px">
    <ng-template let-product pTemplate="item">
        <div class="flex flex-wrap p-2 align-items-center gap-3">
            <img class="w-4rem shadow-2 flex-shrink-0 border-round" src="https://primefaces.org/cdn/primeng/images/demo/product/{{ product.image }}" alt="{item.name}" />
            <div class="flex-1 flex flex-column gap-2">
                <span class="font-bold">{{ product.name }}</span>
                <div class="flex align-items-center gap-2">
                    <i class="pi pi-tag text-sm"></i>
                    <span>{{ product.category }}</span>
                </div>
            </div>
            <span class="font-bold text-900">{{ '$' + product.price }}</span>
        </div>
    </ng-template>
</p-pickList>

Filter #

Filter value is checked against the property of an object configured with the filterBy property.

Available

Selected



<p-pickList [source]="sourceProducts" [target]="targetProducts" sourceHeader="Available" targetHeader="Selected" [dragdrop]="true" [responsive]="true" [sourceStyle]="{ height: '30rem' }"
    [targetStyle]="{ height: '30rem' }" filterBy="name" sourceFilterPlaceholder="Search by name" targetFilterPlaceholder="Search by name" breakpoint="1400px">
    <ng-template let-product pTemplate="item">
        <div class="flex flex-wrap p-2 align-items-center gap-3">
            <img class="w-4rem shadow-2 flex-shrink-0 border-round" src="https://primefaces.org/cdn/primeng/images/demo/product/{{ product.image }}" alt="{item.name}" />
            <div class="flex-1 flex flex-column gap-2">
                <span class="font-bold">{{ product.name }}</span>
                <div class="flex align-products-center gap-2">
                    <i class="pi pi-tag text-sm"></i>
                    <span>{{ product.category }}</span>
                </div>
            </div>
            <span class="font-bold text-900">{{ '$' + product.price }}</span>
        </div>
    </ng-template>
</p-pickList>

Style #

Following is the list of structural style classes, for theming classes visit theming page.

Name	Element
p-picklist	Container element.
p-picklist-source-controls	Container of source list buttons.
p-picklist-target-controls	Container of target list buttons.
p-picklist-buttons	Container of buttons.
p-picklist-list	List element.
p-picklist-item	An item in the list.

Accessibility guide documents the specification of this component based on WCAG guidelines, the implementation is in progress.

Accessibility #

Screen Reader

Value to describe the source listbox and target listbox can be provided with sourceListProps and targetListProps by passing aria-labelledby or aria-label props. The list elements has a listbox role with the aria-multiselectable attribute. Each list item has an option role with aria-selected and aria-disabled as their attributes.

Controls buttons are button elements with an aria-label that refers to the aria.moveTop, aria.moveUp, aria.moveDown, aria.moveBottom,aria.moveTo, aria.moveAllTo, aria.moveFrom and aria.moveAllFrom properties of the locale API by default, alternatively you may usemoveTopButtonProps, moveUpButtonProps, moveDownButtonProps, moveToButtonProps, moveAllToButtonProps, moveFromButtonProps, moveFromButtonProps and moveAllFromButtonProps to customize the buttons like overriding the default aria-label attributes.


<span id="lb">Options</span>        
<p-pickList aria-labelledby="lb"></p-pickList>

<p-pickList aria-label="City"></p-pickList>

PickList Keyboard Support

Key	Function
tab	Moves focus to the first selected option, if there is none then first option receives the focus.
up arrow	Moves focus to the previous option.
down arrow	Moves focus to the next option.
enter	Toggles the selected state of the focused option.
space	Toggles the selected state of the focused option.
home	Moves focus to the first option.
end	Moves focus to the last option.
shift + down arrow	Moves focus to the next option and toggles the selection state.
shift + up arrow	Moves focus to the previous option and toggles the selection state.
shift + space	Selects the items between the most recently selected option and the focused option.
control + shift + home	Selects the focused options and all the options up to the first one.
control + shift + end	Selects the focused options and all the options down to the first one.
control + a	Selects all options.

Buttons Keyboard Support

Key	Function
enter	Executes button action.
space	Executes button action.

PickList API

API defines helper props, events and others for the PrimeNG PickList module.

Properties #

Name	Type	Default	Description
source	array	null	An array of objects for the source list.
target	array	null	An array of objects for the target list.
sourceHeader	string	null	Text for the source list caption
targetHeader	string	null	Text for the target list caption
filterBy	string	null	When specified displays an input field to filter the items on keyup and decides which field to search (Accepts multiple fields with a comma).
filterMatchMode	string	contains	Defines how the items are filtered, valid values are "contains" (default) "startsWith", "endsWith", "equals", "notEquals", "in", "lt", "lte", "gt" and "gte".
filterLocale	string	undefined	Locale to use in filtering. The default locale is the host environment's current locale.
trackBy	Function	null	Function to optimize the dom operations by delegating to ngForTrackBy, default algorithm checks for object identity. Use sourceTrackBy or targetTrackBy in case different algorithms are needed per list.
sourceTrackBy	Function	null	Function to optimize the dom operations by delegating to ngForTrackBy in source list, default algorithm checks for object identity.
targetTrackBy	Function	null	Function to optimize the dom operations by delegating to ngForTrackBy in target list, default algorithm checks for object identity.
showSourceFilter	boolean	true	Whether to show filter input for source list when filterBy is enabled.
showTargetFilter	boolean	true	Whether to show filter input for target list when filterBy is enabled.
dragdrop	boolean	false	Whether to enable dragdrop based reordering.
style	string	null	Inline style of the component.
styleClass	string	null	Style class of the component.
sourceStyle	string	null	Inline style of the source list element.
targetStyle	string	null	Inline style of the target list element.
responsive	boolean	false	When enabled orderlist adjusts its controls based on screen size.
showSourceControls	boolean	true	Whether to show buttons of source list.
showTargetControls	boolean	true	Whether to show buttons of target list.
metaKeySelection	boolean	true	Defines how multiple items can be selected, when true metaKey needs to be pressed to select or unselect an item and when set to false selection of each item can be toggled individually. On touch enabled devices, metaKeySelection is turned off automatically.
sourceFilterPlaceholder	string	null	Placeholder text on source filter input.
targetFilterPlaceholder	string	null	Placeholder text on target filter input.
disabled	boolean	false	When present, it specifies that the component should be disabled.
keepSelection	boolean	false	Keeps selection on the transfer list.
ariaSourceFilterLabel	string	null	Defines a string that labels the filter input of source list.
ariaTargetFilterLabel	string	null	Defines a string that labels the filter input of target list.
rightButtonAriaLabel	string	null	Defines a string that labels the move to right button for accessibility.
leftButtonAriaLabel	string	null	Defines a string that labels the move to left button for accessibility.
allRightButtonAriaLabel	string	null	Defines a string that labels the move to all right button for accessibility.
allLeftButtonAriaLabel	string	null	Defines a string that labels the move to all left button for accessibility.
upButtonAriaLabel	string	null	Defines a string that labels the move to up button for accessibility.
downButtonAriaLabel	string	null	Defines a string that labels the move to down button for accessibility.
topButtonAriaLabel	string	null	Defines a string that labels the move to top button for accessibility.
bottomButtonAriaLabel	string	null	Defines a string that labels the move to bottom button for accessibility.
stripedRows	boolean	false	Whether to displays rows with alternating colors.

Properties #

Name	Parameters	Description
onMoveToTarget	event.items: Moved items array	Callback to invoke when items are moved from source to target.
onMoveToSource	event.items: Moved items array	Callback to invoke when items are moved from target to source.
onMoveAllToTarget	event.items: Moved items array	Callback to invoke when all items are moved from source to target.
onMoveAllToSource	event.items: Moved items array	Callback to invoke when all items are moved from target to source.
onSourceReorder	event.items: Moved items array	Callback to invoke when items are reordered within source list.
onTargetReorder	event.items: Moved items array	Callback to invoke when items are reordered within target list.
onSourceSelect	event.originalEvent: Browser event items: Selected items array	Callback to invoke when items are selected within source list.
onTargetSelect	event.originalEvent: Browser event items: Selected items array	Callback to invoke when items are selected within target list.
onSourceFilter	event.query: Filter value items: Filtered items	Callback to invoke when the source list is filtered
onTargetFilter	event.query: Filter value items: Filtered items	Callback to invoke when the target list is filtered

Templates #

Name	Parameters
item	$implicit: Data of the item index: Index of the item
sourceHeader	-
targetHeader	-
sourceFilter	options.filter: Callback to filter data by the value param options.reset: Resets the filters.
targetFilter	options.filter: Callback to filter data by the value param options.reset: Resets the filters
emptymessagesource	-
emptyfiltermessagesource	-
emptymessagetarget	-
emptyfiltermessagetarget	-
moveupicon	-
movetopicon	-
movedownicon	-
movebottomicon	-
movetotargeticon	$implicit: viewChanged
movealltotargeticon	$implicit: viewChanged
movetosourceicon	$implicit: viewChanged
movealltosourceicon	$implicit: viewChanged
targetfiltericon	-
sourcefiltericon	-

Methods #

Name	Parameters	Description
resetSourceFilter	-	Resets the filters of the source list.
resetTargetFilter	-	Resets the filters of the target list.
resetFilter	-	Resets the filters.