See also: Data TablesLead: Liav Nadler Status
| Table of Contents |
|---|
Description
A dual list selector is a component allowing the user Dual list selectors allow users to select multiple items from a predefined list. It is especially useful when the there is a large number of available items is large.
...
The most A common use of the dual list selector is as a column picker , used in data tables. For this reason, this document describes the structure and function on a column picker.
...
for Data tables.
...
Usage &
...
Behavior
General guidelines
Structure
The dual list selector
...
It is triggered by clicking the Columns action in the column Action Menu
Structure
...
includes:
two multiple selection lists:
On the Selected Columns list, the user can reorder items by selecting them and then clicking the up or down buttons under the list. In this case, reordering multiple items will keep their relative locations (i.e. including gaps between items, if exists)
- The user can also reorder items using /wiki/spaces/~347593403/pages/918783940.
Available Columns (on the left): a list of all columns available for the table
Selected Columns (on the right): a list of the currently displayed columns
Between the two lists there is a set of buttons, allowing the user to move items between them
Under the selected columns list there is a set of buttons, allowing the user the reorder selected items
Next to the selected columns title there is an indicator, showing the number of selected items out of the total number of items (for example: 7/22)
At the top of each list a search bar may appear, allowing the user to quickly locate specific items. The search bar is optional, depending on the number of items
In case the list is too long to be displayed in its container, a vertical scroll bar appears
At the bottom-left corner of the dialog box there is a button titled Restore Defaults
Order
The Selected Columns list shows the list of columns in the same order as they appear on the data table
The Available Columns list is sorted alphanumerically
States
The right and left buttons are disabled until the user selected at least one item: selecting items on the right enables the left button, and vice versa
The up and down buttons are disabled until the user selected at least one item on the Selected Columns list:
Selecting the top item will enable only the down button
Selecting the bottom item will enable only the up button
Selecting any other item will enable both the up and down buttons
If the table contain columns that cannot be removed or reordered, the relevant items on the selected columns list will show as disabled
Interaction
Selecting Items
On either list, clicking an item selects it. The user can select more than one item using the Ctrl (or Command) key for discrete selection, or the Shift key for a block selection
Selecting items on one list deselects all items on the other list
Moving items between lists
The user can move selected items between lists using one of two methods:
Clicking the right or left button between the lists
Using drag and Drop
Items that were moved to the Selected Columns list appears at the bottom of the list
Items that were moved to the Available Columns list appear at their original locations, so the list is always sorted
Items that were moved remain selected
In addition, moved items should be visible. In case the target area is outside of the visible area of the list, it will scroll automatically
Reordering items
additional items above each list.
A header, describing the contents of the list.
A Search bar (optional), allowing users to quickly locate specific items.
A master Checkbox, allowing users to select/deselect all of the items in that list.
Counts of the total number of items and the number of selected items in each list.
Next to the Chosen items list header, an Up to [x] indicator showing the maximum number of allowed items (where relevant).
Where a tree list is used for the Available items, a Collapse/Expand All option will appear next to the master checkbox.
two move buttons (right and left) between the two lists, allowing users to move items between the lists.
two reorder buttons (up and down) below the Chosen items list, allowing users to reorder the chosen items.
a vertical Scrollbar for each list, used if it exceeds its container.
Restore defaults button (optional).
Placement and Positioning
The dual list selector may appear within a Form, either in the main workspace or in a dialog popup.
Data table column selectors are commonly triggered via the Action menu.
Content
Some mandatory items may appear in the Chosen items list by default, and cannot be moved. In this case:
These items will appear first on the list
The associated checkbox for a mandatory item will be disabled.
Internal logic
Available items are often sorted alphanumerically.
Chosen items are shown in the order they were added, unless reordered by the user.
It is possible to select items in both lists. After clicking one of the move buttons, selection will be removed from all items in both lists.
States
The left and right Move buttons are disabled until an item has been selected from the relevant list. Selecting an item in the Available items list enables the right button, and vice versa.
The Reorder buttons are disabled until at least two items are added to the Chosen items list.
The Up button is always disabled when the top item is selected.
The Down button is always disabled when the bottom item is selected.
Interaction
Selecting Items
Items are selected using the checkboxes.
All items in a list can be selected by checking the corresponding master checkbox.
Moving items between lists
Items can be moved between lists by either:
clicking the right or left move buttons, or
using Drag and drop.
Items moved to the Chosen items list will be added to the bottom of the list.
Items returned to the Available items list will return to their original location.
When items are moved using the move buttons, the Chosen items list should automatically scroll so that the first moved item is at the top of the visible area.
When items are moved using drag and drop, the Chosen items list will scroll according to the Drag and drop guidelines.
Reordering the Chosen items list
Items can be reordered by either:
selecting the items and then clicking the up and down buttons underneath the list.
In this case, when reordering multiple items they will keep their relative locations in the list, each moving up or down one place each.
using Drag and drop.
In this case, when reordering multiple items they will be clustered together, and move as a group.
After the items were ordered are reordered they will remain selected until the user selects other items.
Mandatory items in the Chosen items list cannot be reordered.
Restoring Defaults (optional)
Clicking the Restore Defaults button restores the dialog box to its original state (“factory default”)
After clicking the button the user can confirm the action by clicking the Done button, or to cancel
Locking columns (optional)
The user can lock any column on the selected columns list defaults button will return both lists to their original state.
Pinning columns (optional, only relevant for table column selectors)
For table column selectors, items in the Chosen items list may be pinned to the top. This will ensure that these columns are always visible on the table, and remain static when there is horizontal scroll.
State | How the item looks on the Visible Items list | How the table would look |
|---|---|---|
A mandatory column (always pinned) |  |  When scrolled:  |
Before pinning the item (the user hovers over the item) |  |
|
After pinning the item. |  |
|
Where defined, users can pin any items within the Chosen items. Within a Data table column selector, pinned items represent columns which are anchored to the left of the table and do not move with horizontal scroll (where it exists).
Mandatory items are always pinned automatically.
Items are pinned by clicking the pin icon, which is shown on hover. In this case:
The icon changes from idle to selected
The item moves When the pin icon is selected, the item will automatically move to the top of the list
The item can be ordered only inside the group of locked items
On the actual table the locked columns are anchored to the left. Locked items can be reordered only inside the group of locked items
The user can unlock the column by clicking the lock icon again
. The icon toggles between pinned and unpinned states.
 |
Validation and Errors
Removing All Items
If the user removed all items from the Selected Columns list:
The search bar and reordering buttons get disabled
A message appears inside the container, guiding Pinned items can only be ordered within the pinned items group. Note: mandatory items cannot be moved.
, beneath the preexisting pinned items.
Validation and Errors
No items on the chosen columns list
If all items are removed from the Chosen items list:
the search bar, reordering buttons, and Apply button are all disabled.
a message will appear within the Chosen items area, advising the user to select at least one item.
 |
In this case, clicking the Done button:
Shows an error message at the bottom of the dialog
Disables the button
 |
Limiting the Number of Items
It is recommended to limit the number of selected items, depending on common usage and system performance
In this case, the maximum number of items will be presented within the indicator at the top of the Selected Columns list, regardless of the number of available columns
If the user reached the maximum number of items:
The right arrow button will be disabled
Dragging items from the Available Columns list will be disabled
A relevant message will appear at the bottom of the popup
 |
Accessibility compliance
<<In general each component should be A11y complied, please follow the 3 guidelines linked below. At the very least we should document that each component is in compliance with each of the 3>>
Focus management
<<How will the component work with keyboard only - without a mouse. Can be reference if written above
We already set a general guidelines described in /wiki/spaces/UX/pages/308969693 >>
Screen reader support
<<Make sure the components support screen reader for content or behaviour where needed - see /wiki/spaces/UX/pages/308248620 >>
Contrast & size compliance
...
Exceeding the Chosen items limit
There is no restriction on how many items can be moved to the Chosen items list.
If there is a limit on the number of items which can be applied, and the number of items in the list exceeds this limit:
the Apply button is disabled.
an error message will appear underneath the lists.
...
Best practices
Where used as a table column selector:
do not make more than one item mandatory.
do not pin more than three items, as the table will not be usable at narrow screen widths with horizontal scroll.
Accessibility compliance
Unless otherwise specified, see our general compliance information in Fundamentals - Accessibility.
Focus management
Generally the focus will behave as in other Forms.
...
There is one variation on this behavior: When the focus is on the Chosen items list, and the user moves one or more selected items to the bottom of the list, the focus will move to the Up arrow (9) (instead of to the next focusable element).
If the user moves all the items from the chosen items list back to the available items list, the focus will automatically move from the left move button (5) to the the right move button (4).
Design
Code
...
Happy trailInitial state  Selecting items  After adding items to the chosen list  Edge casesNo items chosen  Maximum items exceeded  OptionalGrouped items  |
Code
...