PickList

PickList is used to reorder items between different lists.

Import #


import { PickList } 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.

No selected item


<p-picklist [source]="sourceProducts" [target]="targetProducts" [dragdrop]="true" [responsive]="true" [sourceStyle]="{ height: '30rem' }" [targetStyle]="{ height: '30rem' }" breakpoint="1400px">
    <ng-template let-item pTemplate="item">
        {{ item.name }}
    </ng-template>
</p-picklist>

Filter #

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

Search results are available

No selected item

No results found

No selected item


<p-picklist
    [source]="sourceProducts"
    [target]="targetProducts"
    [dragdrop]="true"
    [responsive]="true"
    [sourceStyle]="{ height: '30rem' }"
    [targetStyle]="{ height: '30rem' }"
    filterBy="name"
    sourceFilterPlaceholder="Search by name"
    targetFilterPlaceholder="Search by name"
    breakpoint="1400px"
    scrollHeight="30rem"
>
    <ng-template let-option let-selected="selected" pTemplate="option">
        <div class="flex flex-wrap p-1 items-center gap-4 w-full">
            <img
                class="w-12 shrink-0 rounded"
                src="https://primefaces.org/cdn/primeng/images/demo/product/{{ option.image }}"
                [alt]="option.name"
            />
            <div class="flex-1 flex flex-col">
                <span class="font-medium text-sm">{{ option.name }}</span>
                <span
                    [ngClass]="{
                        'text-surface-500': !selected,
                        'dark:text-surface-400': !selected,
                        'text-inherit': selected,
                    }"
                    >{{ option.category }}</span
                >
            </div>
            <span class="font-bold sm:ml-8">{{ '$' + option.price }}</span>
        </div>
    </ng-template>
</p-picklist>

Template #

For custom content support define an option template that gets the item instance as a parameter. In addition sourceheader and targetheader templates are provided for further customization.

No selected item


<p-picklist
    [source]="sourceProducts"
    [target]="targetProducts"
    [dragdrop]="true"
    [responsive]="true"
    [sourceStyle]="{ height: '30rem' }"
    [targetStyle]="{ height: '30rem' }"
    filterBy="name"
    sourceFilterPlaceholder="Search by name"
    targetFilterPlaceholder="Search by name"
    breakpoint="1400px"
    scrollHeight="480px"
>
    <ng-template let-option let-selected="selected" pTemplate="option">
        <div class="flex flex-wrap p-1 items-center gap-4 w-full">
            <img
                class="w-12 shrink-0 rounded"
                src="https://primefaces.org/cdn/primeng/images/demo/product/{{ option.image }}"
                [alt]="option.name"
            />
            <div class="flex-1 flex flex-col">
                <span class="font-medium text-sm">{{ option.name }}</span>
                <span
                    [ngClass]="{
                        'text-surface-500': !selected,
                        'dark:text-surface-400': !selected,
                        'text-inherit': selected,
                    }"
                    >{{ option.category }}</span
                >
            </div>
            <span class="font-bold sm:ml-8">{{ '$' + option.price }}</span>
        </div>
    </ng-template>
</p-picklist>

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.

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	"gt" \| "lt" \| "in" \| "startsWith" \| "contains" \| "endsWith" \| "equals" \| "notEquals" \| "lte" \| "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.
scrollHeight	string	14rem	Height of the viewport, a scrollbar is defined if height of list exceeds this value.
autoOptionFocus	boolean	true	Whether to focus on the first visible or selected element.
buttonProps	ButtonProps	...	Used to pass all properties of the ButtonProps to the Button component.
moveUpButtonProps	ButtonProps	null	Used to pass all properties of the ButtonProps to the move up button inside the component.
moveTopButtonProps	ButtonProps	null	Used to pass all properties of the ButtonProps to the move top button inside the component.
moveDownButtonProps	ButtonProps	null	Used to pass all properties of the ButtonProps to the move down button inside the component.
moveBottomButtonProps	ButtonProps	null	Used to pass all properties of the ButtonProps to the move bottom button inside the component.
moveToTargetProps	ButtonProps	null	Used to pass all properties of the ButtonProps to the move to target button inside the component.
moveAllToTargetProps	ButtonProps	null	Used to pass all properties of the ButtonProps to the move all to target button inside the component.
moveToSourceProps	ButtonProps	null	Used to pass all properties of the ButtonProps to the move to source button inside the component.
moveAllToSourceProps	ButtonProps	null	Used to pass all properties of the ButtonProps to the move all to source button inside the component.
breakpoint	string	null	Indicates the width of the screen at which the component should change its behavior.

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

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.

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

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

PickList

Import #

Basic #

Filter #

Template #

Accessibility #

Screen Reader

PickList Keyboard Support

Buttons Keyboard Support

PickList API

PickList #

Properties #

Emitters #

Templates #

Events #

PickListMoveToSourceEvent #

PickListMoveAllToSourceEvent #

PickListMoveAllToTargetEvent #

PickListMoveToTargetEvent #

PickListSourceReorderEvent #

PickListTargetReorderEvent #

PickListSourceSelectEvent #

PickListTargetSelectEvent #

PickListSourceFilterEvent #

PickListTargetFilterEvent #

Interfaces #

PickListFilterOptions #

PickList Theming

CSS Classes #

PickList Design Tokens #

class	description
p-picklist	Class name of the root element
p-picklist-source-controls	Class name of the source controls element
p-picklist-source-list-container	Class name of the source list container element
p-picklist-transfer-controls	Class name of the transfer controls element
p-picklist-target-list-container	Class name of the target list container element
p-picklist-target-controls	Class name of the target controls element

token	variable	description
picklist.gap	--p-picklist-gap	Gap of root
picklist.controls.gap	--p-picklist-controls-gap	Gap of controls