Introduction

jqxPickList is a dual-list picker, sometimes called a shuttle or transfer list: the items that are available on the left, the items that are chosen on the right, and buttons, a double-click or the keyboard to move them across. It is the control for picking a subset from a set - the columns of a report, the people on a team, the roles of a user, the panels on a dashboard - when a drop-down would hide the choice and a row of checkboxes would not scale. Both lists are jqxListBox instances, so everything the list box does - virtualization for thousands of items, filtering, checkboxes, keyboard navigation, templates - the pick list does too, and it works the same in jQuery, JavaScript, Angular, React and Vue.

Features

• Two lists and four transfer buttons: add, add all, remove, remove all
• Single, Ctrl and Shift selection, or checkboxes
• A search box above each list
• Reordering of the selected list, with Move up and Move down
• Object items with displayMember and valueMember
• Item templates through a renderer callback
• Headers with live item counts
• Keyboard navigation and screen reader support
• Right-to-left layout
• Great Performance with thousands of items
• Rich and easy to use JavaScript API
• Easy customization and built-in themes

Selection and Transfer

Click an item to select it, Ctrl+click to add another, Shift+click to select a range, then use the arrows between the lists: a single arrow moves what is selected, a double arrow moves everything. Double-clicking an item moves it straight across. The headers show how many items each list holds, and the buttons enable and disable themselves as the selection changes. Every transfer raises an itemsAdded or itemsRemoved event with the items that moved, followed by a change event with the whole selection.

Filtering and Checkboxes

With filterable: true a search box appears above each list, and typing narrows that list as you go - by default matching anywhere in the item, so a team name in brackets is found as easily as a first name. With checkboxes: true a click ticks an item without dropping the others, which is the natural way to pick many items from a long list. Together they make a picker for hundreds of items usable.

Reordering

When the order of the selection matters - columns left to right, panels top to bottom, steps in a sequence - set reorderable: true. Move up and Move down buttons appear for the selected list, the reordered event reports the new order, and getSelectedValues() always returns the items in the order shown.

Object Items

Bind the picker to an array of objects and name the fields with displayMember and valueMember: the user sees names, the application works with ids. selectedItems, val() and getSelectedValues() speak in values; getSelectedItems() returns the original objects.

Item Templates

The renderer callback receives each item and returns the HTML for its row - an avatar and two lines of text, an icon and a label, a colour swatch - and itemHeight makes room for it. Selection, transfer, filtering and keyboard navigation work exactly as with plain text items.

Keyboard Navigation and Accessibility

Tab moves between the two lists and the transfer buttons. Inside a list, the arrow keys move the selection, Home and End jump to the first and last item, Page Up and Page Down move by a page, and Space ticks an item when checkboxes are on. The buttons are real buttons with accessible names - "Add selected", "Remove all", "Move up" - and each list is labelled for screen readers through sourceLabel and targetLabel.

API

Everything the buttons do, the application can do: add(), remove(), addAll(), removeAll(), moveUp(), moveDown(), val(), getSelectedItems() and getSelectedValues() - for presets, "select all matching", or restoring a saved selection. The complete list of properties, methods and events is in the API reference.

Angular, React and Vue

The same component ships for Angular as jqxPickListComponent from jqwidgets-ng/jqxpicklist, for React as JqxPickList from jqwidgets-scripts/jqwidgets-react-tsx/jqxpicklist, and for Vue 3 as jqwidgets-scripts/jqwidgets-vue3/vue_jqxpicklist.vue, with the same options, events and methods.