OrderList

OrderList is used to sort a collection.

Import #


import { OrderList } from 'primeng/orderlist';

Basic #

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

No selected item


<p-orderlist [value]="products" dataKey="id" breakpoint="575px">
    <ng-template pTemplate="option" let-option>
        {{ option.name }}
    </ng-template>
</p-orderlist>

Filter #

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

Search results are available

No selected item


<p-orderlist
    [value]="products"
    [listStyle]="{ 'max-height': '30rem' }"
    filterBy="name"
    filterPlaceholder="Filter by name"
>
    <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-sm': true,
                        '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-orderlist>

Template #

For custom content support define an option template that gets the item instance as a parameter. In addition header template is provided for further customization.

No selected item


<p-orderlist
    [value]="products"
    dataKey="id"
    breakpoint="575px"
    scrollHeight="20rem"
>
    <ng-template let-option let-selected="selected" #item>
        <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-sm': true,
                        '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-orderlist>

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-orderlist ariaLabelledBy="lb" />

<p-orderlist ariaLabel="City" />

OrderList 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
header	string	null	Text for the caption.
style	Object	null	Inline style of the component.
styleClass	string	null	Style class of the component.
tabindex	number	null	Index of the element in tabbing order.
ariaLabel	string	null	Defines a string that labels the input for accessibility.
ariaLabelledBy	string	null	Specifies one or more IDs in the DOM that labels the input field.
listStyle	Object	null	Inline style of the list element.
responsive	boolean	false	A boolean value that indicates whether the component should be responsive.
filterBy	string	null	When specified displays an input field to filter the items on keyup and decides which fields to search against.
filterPlaceholder	string	null	Placeholder of the filter input.
filterLocale	string	null	Locale to use in filtering. The default locale is the host environment's current locale.
metaKeySelection	boolean	false	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.
controlsPosition	"right" \| "left"	left	Defines the location of the buttons with respect to the list.
ariaFilterLabel	string	null	Defines a string that labels the filter input.
filterMatchMode	"gt" \| "lt" \| "in" \| "startsWith" \| "contains" \| "endsWith" \| "equals" \| "notEquals" \| "lte" \| "gte"	contains	Defines how the items are filtered.
breakpoint	string	960px	Indicates the width of the screen at which the component should change its behavior.
stripedRows	boolean	false	Whether to displays rows with alternating colors.
disabled	boolean	false	When present, it specifies that the component should be disabled.
trackBy	Function	...	Function to optimize the dom operations by delegating to ngForTrackBy, default algorithm checks for object identity.
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.
selection	any[]	null	A list of values that are currently selected.
value	any[]	null	Array of values to be displayed in the component. It represents the data source for the list of items.
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.

name	parameters	description
selectionChange	value : any	Callback to invoke on selection change.
onReorder	value : any	Callback to invoke when list is reordered.
onSelectionChange	event : OrderListSelectionChangeEvent	Callback to invoke when selection changes.
onFilterEvent	event : OrderListFilterEvent	Callback to invoke when filtering occurs.
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, // Index of the item. }	Custom header template.
header		Custom header template.
filter	context : { options: OrderListFilterOptions, // Filter options. }	Custom filter template.
emptyfilter		Custom empty filter template.
empty		Custom empty template.
clearicon		Custom clear icon template.
filtericon		Custom filter icon 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.

name	type	description
originalEvent	Event	Browser event.
value	any[]	Current selected values.

name	type	description
originalEvent	Event	Browser event.
value	any[]	Filtered options.

OrderList

Import #

Basic #

Filter #

Template #

Accessibility #

Screen Reader

OrderList Keyboard Support

Buttons Keyboard Support

OrderList API

OrderList #

Properties #

Emitters #

Methods #

Templates #

Events #

OrderListSelectionChangeEvent #

OrderListFilterEvent #

Interfaces #

OrderListFilterOptions #

OrderList Theming

CSS Classes #

OrderList Design Tokens #

class	description
p-orderlist	Class name of the root element
p-orderlist-controls	Class name of the controls element

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