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. Drag & drop functionality depends on @angular/cdk package.

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 #

Screen Reader

Value to describe the source listbox and target listbox can be provided with ariaLabelledBy or ariaLabel 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 ariaLabelledBy="lb" />

<p-pickList ariaLabel="City" />

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.

PickList #

PickList is used to reorder items between different lists.

Properties #

Defines the input properties of the component.

name	type	default	description
source	any[]	null	An array of objects for the source list.
target	any[]	null	An array of objects for the target list.
sourceHeader	string	null	Text for the source list caption
tabindex	number	0	Index of the element in tabbing order.
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.
targetHeader	string	null	Text for the target list caption
responsive	boolean	false	When enabled orderlist adjusts its controls based on screen size.
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).
filterLocale	string	null	Locale to use in filtering. The default locale is the host environment's current locale.
trackBy	Function	...	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.
metaKeySelection	boolean	false	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.
dragdrop	boolean	false	Whether to enable dragdrop based reordering.
style	Object	null	Inline style of the component.
styleClass	string	null	Style class of the component.
sourceStyle	any	null	Inline style of the source list element.
targetStyle	any	null	Inline style of the target list element.
showSourceControls	boolean	true	Whether to show buttons of source list.
showTargetControls	boolean	true	Whether to show buttons of target list.
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.
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.
filterMatchMode	"endsWith" \| "startsWith" \| "contains" \| "equals" \| "notEquals" \| "in" \| "lt" \| "lte" \| "gt" \| "gte"	contains	Defines how the items are filtered.
stripedRows	boolean	false	Whether to displays rows with alternating colors.
keepSelection	boolean	false	Keeps selection on the transfer list.
breakpoint	string	null	Indicates the width of the screen at which the component should change its behavior.

Emitters #

Defines emit that determine the behavior of the component based on a given condition or report the actions that the component takes.

name	parameters	description
onMoveToSource	event : PickListMoveToSourceEvent	Callback to invoke when items are moved from target to source.
onMoveAllToSource	event : PickListMoveAllToSourceEvent	Callback to invoke when all items are moved from target to source.
onMoveAllToTarget	event : PickListMoveAllToTargetEvent	Callback to invoke when all items are moved from source to target.
onMoveToTarget	event : PickListMoveToTargetEvent	Callback to invoke when items are moved from source to target.
onSourceReorder	event : PickListSourceReorderEvent	Callback to invoke when items are reordered within source list.
onTargetReorder	event : PickListTargetReorderEvent	Callback to invoke when items are reordered within target list.
onSourceSelect	event : PickListSourceSelectEvent	Callback to invoke when items are selected within source list.
onTargetSelect	event : PickListTargetSelectEvent	Callback to invoke when items are selected within target list.
onSourceFilter	event : PickListSourceFilterEvent	Callback to invoke when the source list is filtered
onTargetFilter	event : PickListTargetFilterEvent	Callback to invoke when the target list is filtered
onFocus	event : Event	Callback to invoke when the list is focused
onBlur	event : Event	Callback to invoke when the list is blurred

Templates #

Defines the templates used by the component.

name	parameters	description
item	context : { $implicit: any, // Item instance. index: number, // Item index. }	Custom item template.
sourceHeader		Custom source header template.
targetHeader		Custom target header template.
sourceFilter	context : { options: PickListFilterOptions, // Source filter options. }	Custom source filter template.
targetFilter	context : { options: PickListFilterOptions, // Target filter options. }	Custom target filter template.
emptymessagesource		Custom source list empty message template.
emptyfiltermessagesource		Custom source list empty filter message template.
emptymessagetarget		Custom target list empty message template.
emptyfiltermessagetarget		Custom target list empty filter message template.
moveupicon		Custom move up icon template.
movetopicon		Custom move top icon template.
movedownicon		Custom move down icon template.
movebottomicon		Custom move bottom icon template.
movetotargeticon	context : { $implicit: boolean, // Boolean value indicates if the view is changed according to breakpoints. }	Custom move to target icon template.
movealltotargeticon	context : { $implicit: boolean, // Boolean value indicates if the view is changed according to breakpoints. }	Custom move all to target icon template.
movetosourceicon	context : { $implicit: boolean, // Boolean value indicates if the view is changed according to breakpoints. }	Custom move to source icon template.
movealltosourceicon	context : { $implicit: boolean, // Boolean value indicates if the view is changed according to breakpoints. }	Custom move all to source icon template.
targetfiltericon		Custom target filter icon template.
sourcefiltericon		Custom source filter icon template.

Events #

Defines the custom events used by the component's emitters.

PickListMoveToSourceEvent #

Custom move to source event.

name	type	description
items	any[]	Moved items.

PickListMoveAllToSourceEvent #

Custom move all to source event.

name	type	description
items	any[]	Moved items.

PickListMoveAllToTargetEvent #

Custom move all to target event.

name	type	description
items	any[]	Moved items.

PickListMoveToTargetEvent #

Custom move to target event.

name	type	description
items	any[]	Moved items.

PickListSourceReorderEvent #

Custom move source reorder event.

name	type	description
items	any[]	Moved items.

PickListTargetReorderEvent #

Custom move target reorder event.

name	type	description
items	any[]	Moved items.

PickListSourceSelectEvent #

Custom source select event.

name	type	description
originalEvent	Event	Browser event.
items	any[]	Selected items.

PickListTargetSelectEvent #

Custom target select event.

name	type	description
originalEvent	Event	Browser event.
items	any[]	Selected items.

PickListSourceFilterEvent #

Custom source filter event.

name	type	description
query	string	Filter value.
value	any[]	Filtered items.

PickListTargetFilterEvent #

Custom target filter event.

name	type	description
query	string	Filter value.
value	any[]	Filtered items.

Interfaces #

Defines the custom interfaces used by the module.

PickListFilterOptions #

Callbacks to invoke on filter.

name	type	description
filter	Function
reset	Function