Skip to content

docs(dual-list-selector): Updates design guidelines for accuracy and readability. #4617

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs(dual-list-selector): Updates design guidelines for accuracy and readability. #4617

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
90 changes: 50 additions & 40 deletions ...s/content/design-guidelines/components/dual-list-selector/dual-list-selector.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,83 +3,93 @@ id: Dual list selector
section: components
---

import '../components.css';

## Elements

The following image is a basic dual list selector. For details about the elements for expandable dual lists, refer to [the variations section](#variations).

<div class="ws-docs-content-img">
![dual list with 2 search bars and 2 rows of items](./img/dual-list-elements.svg)
</div>

1. **List labels:** Distinguish between the list of available options and the list of chosen options. You can change these for your use case, but they should remain clear and concise.
2. **Available options:** List of items that users can choose from. This list can have a single level or multiple levels.
3. **Chosen options:** List of items that users have selected from the available options list.
4. **Selected item:** A visual state for items selected by a user.
5. **Arrows:** Buttons that allow users to move items between lists. These buttons are enabled and disabled based on user selections. Single arrows only move selected items, while double arrows move everything in one list to the other&mdash;in the direction of the arrow.
6. **Number of items:** Indicator of the number of selected items compared to the total available items.
7. **Filter:** Search field that allows users to filter the list of items.
8. **Sorting (optional):** Enables users to sort the list of items for easier scanning.
9. **More actions (optional):** Stores additional actions, such as Export.

## Usage
Dual list selectors are useful when you have a large set of options for users to pick from that would be difficult to digest in a select list. They’re useful in forms, wizards, and modals as a way for users to make selections from a list of options.
Dual list selectors are useful when there are a large set of options for users to choose from, which would be more difficult to understand in a menu. They’re useful in forms, wizards, and modals as a way for users to make selections from a list of options.

### When to use

* You have a long list of items for users to pick from.
* You want to distinguish the available items from the chosen items.
* You want the ability to group the list of items
* The user can select a large number of items and separating selections from available options would be helpful.
* You want the ability to group the list of items.
* Users can select a large number of items, and it would be helpful to distinguish selections from available options.

### When not to use
* Users have a list of actions to choose from. Instead, use a dropdown menu or tree view
* The list of items to choose from has fewer than 20 items. Instead, use a select list.
* Users have a list of actions to choose from. Instead, use a dropdown menu or tree view.
* The list of items to choose from has fewer than 20 items. Instead, use a select menu.

## Behavior
Users can select one or more items from the available list and use the arrows to move these items to the chosen list. Users can filter down the items by using the search input field.
Users can select 1 or more items from the available options, using the arrows to move these items to the chosen options list. Users can filter down the items by using the search input field.

<div class="ws-docs-content-img">
![dual list behavior with an item being moved to the second row](./img/dual-list-1.gif)
</div>

In an expandable dual list, when users move an item from the available list to the chosen list, the item still appears in its original group structure. For example, if the item Broccoli in the group Folder Vegetables is moved from the available list to the chosen list, the Broccoli item will appear in the chosen list under the Vegetable group. It won’t appear as a stand-alone, single-level item.
In an expandable dual list, when users move an item to the chosen list, the item still appears in its original group structure. For example, if the item Broccoli in the group Vegetables is moved from the available list to the chosen list, the Broccoli item will appear in the chosen list under the Vegetable group. It won’t appear as a stand-alone, single-level item.

<div class="ws-docs-content-img">
![dual list behavior with 1 folder of item being moved to the second row](./img/dual-list-2.gif)
</div>

## Variations
There are two types of dual list selectors: basic dual lists and expandable dual lists.

### Basic dual list
A basic dual list contains a flat list of items for the user to choose from.
### Drag and drop functionality
Drag and drop functionality allows users to customize the order of items in the chosen options. The fa-grip icon at the start of the item row indicates that an item is draggable.

<div class="ws-docs-content-img">
![dual list with 2 search bars and 2 rows of items](./img/basic-dual-list.svg)
![dual list with the second row item being dragged to a new position](./img/ondrag-event.svg)
</div>

1. **List labels:** List labels distinguish between the list of available items and the list of chosen items. These labels can be changed based on your use case, and they should be clear and concise.
2. **Available items list:** The available items list is a list of items that users can choose from. Available list items can have a single level or multiple levels.
3. **Chosen items list:** The chosen items list is a list of items that users have selected and moved from the available items list.
4. **Selected item:** A selected item refers to the visual state of the item when it has been selected by a user.
5. **Arrows:** Arrows are buttons that give users the ability to move items from one list to another. The arrows will enable and disable based on user selections. Single arrows move only selected items. Double arrows move everything from one list to the other (in the direction of the arrow), whether the list contains manually selected items or not.
6. **Number of items:** The number of items is an indicator of how many items are selected among the total items available in the list.
7. **Filter:** The filter is a search field that allows users to filter the list of items.
8. **Sorting (optional):** The sorting ability enables users to sort the list of items presented for easier scanning.
9. **More actions (optional):** The more actions (kebab) menu stores added actions, such as exporting.

### Expandable dual list
An expandable dual list contains a multi-leveled list of items for users to choose from. Items can be nested in a hierarchical tree to show different groupings or categories, and the list can have up to three levels.
1. **Ghost item:** Upon click and hold, a duplicate "ghost" item with a `--pf-v6-global--active-color--100` border will appear "on top" of the list. This ghost item represents the initial item being moved.

<div class="ws-docs-content-img">
![dual list with 2 rows of items of expandable items](./img/expandable-dual-list.svg)
![dual list that is actively being dragged with a ghost row](./img/ghost-row.svg)
</div>

1. **Number of items:** indicator of how many items are selected, among the total items available in the list. <u>In expandable lists, only non-folder items are included in the item count.</u>
2. **Folder:** group of items that can be selected and moved from one list of options to the other. When a folder has a mix of selected and unselected items, the checkbox should have a mixed state. When all items in a folder are selected, the folder checkbox should have a selected state.
3. **Selected item:** visual state of an item when it has been selected by a user.
4. **Item:** item within a folder that can be selected and moved.
5. **Badge (optional):** number of items inside a folder.

### Drag and drop dual list
Drag and drop functionality inside of a dual list allows users to customize the order in which items within the Chosen options are displayed. The fa-grip icon at the start of the item row is used to indicate that the items are draggable.
2. **onDrag event:** While a ghost item is being dragged, the original item will move its position in the list to align with the hovered position.

<div class="ws-docs-content-img">
![dual list with the second row item being dragged to a new position](./img/ondrag-event.svg)
![dual list with an item that was dragged from one position to another](./img/postdrag-event.svg)
</div>

1. **onDrag event:** Upon click & hold a `--pf-t--global--border--color--brand--clicked` border will show the draggable area that is available. The list item being dragged will also use a `--pf-t--global--border--color--brand--clicked` border to highlight it as the item being dragged.
3. **postDrag event:** Once dropped, the ghost item will become an item in the list, which will be reordered based on the user’s action.

## Variations
There are 2 types of dual list selectors: basic dual lists and expandable dual lists.

### Basic dual list
A basic dual list contains a flat list of items for the user to choose from.

<div class="ws-docs-content-img">
![dual list that is acitvely being dragged with a ghost row](./img/ghost-row.svg)
![dual list with 2 rows of items of expandable items](./img/basic-dual-list.svg)
</div>

2. **Ghost row:** Mid onDrag event, a duplicate ghost row will follow the active dragged item. The ghost row will fill the available space and use a `--pf-t--global--border--color--brand--clicked` border to highlight it as the item being dragged. The ghost row icon button will recieve a hover fill using `--pf-t--global--background--color--action--plain--hover`.
### Expandable dual list
An expandable dual list contains a multi-leveled list of items for users to choose from. Items can be nested in a hierarchical tree to show different groupings or categories, and the list can have up to 3 levels.

<div class="ws-docs-content-img">
![dual list with an item that was dragged from one position to another](./img/postdrag-event.svg)
![dual list with 2 rows of items of expandable items](./img/expandable-dual-list.svg)
</div>

3. **postDrag event:** Once dropped, the items will be reordered based on the user’s action. The recently dropped row will receive a hover fill using `--pf-t--global--background--color--primary--hover`and the icon button will receive a background fill of `--pf-t--global--background--color--action--plain--hover`.
1. **Number of items:** Indicates the number of selected items out of the total available. In expandable lists, only non-folder items are included in the item count.
2. **Folder:** Group of items that can be moved between lists. When a folder has a mix of selected and unselected items, the checkbox should have a mixed state. When all items in a folder are selected, the folder checkbox should have a selected state.
3. **Selected item:** A visual state for items selected by a user.
4. **Selectable item:** Item within a folder that can be selected and moved.
5. **Badge (optional):** Indicated the number of items inside a folder.
Loading