Skip to content

docs(list, simple list, data list, description list): Updates images … #4542

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

Merged
andrew-ronaldson merged 2 commits into from
Apr 23, 2025
Merged

docs(list, simple list, data list, description list): Updates images … #4542

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
10b02ee
docs(list, simple list, data list, description list): Updates images …
bekah-stephens Apr 10, 2025
fd6d690
Merge branch 'main' into iss#4520
andrew-ronaldson Apr 23, 2025
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
52 changes: 39 additions & 13 deletions ...ite/patternfly-docs/content/design-guidelines/components/data-list/data-list.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,15 @@ section: components
related: ['Table']
---

import '../components.css';

## Elements

The elements mentioned below are similar for a data list with compact or default spacing. This example shows a data list with compact spacing.

<img src="./img/datalist-elements.png" alt="example of elements on a data list" width="1273"/>
<div class="ws-docs-content-img">
![Elements of a data list](./img/datalist-elements.svg)
</div>

1. **[Toolbar](/components/toolbar/design-guidelines):** Sits above the list and contains controls for manipulating list data. Common actions include filtering, sorting, and pagination.
2. **[Bulk selection](/patterns/bulk-selection):** When present, selects all items in a table. If pagination is being used, this will only select items on the current page. See [bulk selection](/patterns/bulk-selection) for more information.
Expand All @@ -20,6 +25,7 @@ The elements mentioned below are similar for a data list with compact or default


## Usage

Think of each row in a data list as a container for some formatted content. In PatternFly, data list rows can accept any [layout](/layouts/bullseye) supported by the design system as long as all rows apply the same layout. Here are some common layouts that may be useful in a data list:

* **[Grid](/layouts/grid):** Displays content in a responsive grid.
Expand All @@ -42,14 +48,17 @@ Data lists can also appear in primary-detail views. Visit the [primary-detail gu
* The clarity of your content would benefit from well defined columns and headings.

## Variations

PatterFly supports 2 main types of data lists:

1. **[Compact data list](#compact-spacing):** Use when you want to show as much data per page as possible.
2. **[Default data list](#default-spacing):** Use when you don’t have to minimize paging.

See [when to use compact vs. default spacing](#when-to-use-a-data-list-vs.-a-table)for more information about the styling and usage.

<img src="./img/compact-and-default-list.png" alt="Compact and default data list" />
<div class="ws-docs-content-img">
![Examples of compact and default data lists.](./img/datalist-variations.svg)
</div>

### Data list capabilities
Every data list can be extended with these functionalities:
Expand All @@ -62,7 +71,9 @@ Every data list can be extended with these functionalities:
### Selectable data list
The selectable data list provides checkboxes that enable users to select one or more rows in the list. Users may then act on those selections using options in the [toolbar](/components/toolbar/design-guidelines).

<img src="./img/datalist-selectable.png" alt="example of selectable data list" width="1214"/>
<div class="ws-docs-content-img">
![Example of a selectable data list.](./img/datalist-selectable.svg)
</div>

1. **[Bulk selection](/patterns/bulk-selection):** When present, selects all items in a table. If pagination is being used, this will only select items on the current page. See [bulk selection](/patterns/bulk-selection) for more information.
2. **Checkbox:** Enables a user to select a row.
Expand All @@ -77,7 +88,9 @@ The selectable data list provides checkboxes that enable users to select one or
### Clickable data list
The clickable data list can be used when data lists need to provide additional information while keeping the row information available via a primary-detail drawer. This can be done by clicking on the row itself.

<img src="./img/datalist-clickable.png" alt="example of clickable data list" width="2606"/>
<div class="ws-docs-content-img">
![Example of a clickable data list.](./img/datalist-clickable.svg)
</div>

1. **Row:** Enables the user to click on the row to trigger the action of opening a primary-detail drawer
2. **Primary-detail:** Additional drawer of information that allows the user to still see the data list
Expand All @@ -90,7 +103,9 @@ The clickable data list can be used when data lists need to provide additional i
### Expandable data list
The expandable list adds an expansion panel to every row to reveal more details about the item.

<img src="./img/datalist-expandable.png" alt="example of expandable data list" width="1273"/>
<div class="ws-docs-content-img">
![Example of an expandable data list.](./img/datalist-expandable.svg)
</div>

1. **Expand all (optional):** Expands or collapses every row in the data list at the same time.
2. **Expansion caret:** Toggles the expansion open and closed for the individual row.
Expand All @@ -103,23 +118,37 @@ The expandable list adds an expansion panel to every row to reveal more details
* You want to provide a way for advanced users to access information that is not applicable to all users.

### Draggable data list rows

Draggable data list rows can be added to any data list and allow you to customize the order of rows within a data list.

<img src="./img/datalist-draggable1.png" alt="example of draggable data list" width="1011"/>

1. **Drag icon:** To indicate a row is draggable, use the fa-grip icon. Use grip-vertical to indicate the ability to move a vertically-oriented component via drag and drop. Use grip-horizontal to move a horizontally-oriented component via drag and drop. For example, if you are selecting items to be dragged from two parallel lists.

<div class="ws-docs-content-img">
![Example of a draggable data list.](./img/datalist-draggable1.svg)
</div>

2. **Dragged row:** When dragging a row, it becomes slightly less opaque and floats above the static rows to indicate that it is the one moving.

<img src="./img/datalist-draggable2.png" alt="example of draggable data list" width="1006"/>
<div class="ws-docs-content-img">
![Example of a data list item being dragged.](./img/datalist-draggable2.svg)
</div>

3. **Dragged row positioning:** When positioning the row, the other elements in the data list will move to indicate the dragged row’s position.

<div class="ws-docs-content-img">
![Example of a data list being reordered on drag.](./img/datalist-draggable3.svg)
</div>

4. **Final position:** After the row has been placed where desired, the data list becomes static again, until the user decides to drag another row.

<div class="ws-docs-content-img">
![Example of a reordered data list after dragging an item.](./img/datalist-draggable4.svg)
</div>

#### When to use
Use draggable data list rows when you want to allow users to order their choices within a list. A common example of this is [column management](/components/table/react-demos#column-management-with-draggable). Users can choose the number of columns and the order they are shown in a table by selecting and dragging rows in the **Manage columns** modal. Another common use case is ordering the importance of roles or types relative to a resource.

## Spacing

Whether to use a data list with compact or default spacing is up to you and your use case. However, here is some guidance for when to use which option. You can see examples of each option for comparison.

### Compact spacing
Expand All @@ -131,8 +160,6 @@ A data list may sometimes need to be compact to make more rows visible at a time
* You need to minimize paging.
* Readability is a secondary concern.

<img src="./img/compact-datalist.png" alt="Example of compact spacing data list" width="990"/>

**Example:**
* You can see more data on one page.
* You have a good overview about the structure of data.
Expand All @@ -147,12 +174,11 @@ A data list may sometimes need more space for rich graphical data. See an exampl
* You don't have to minimize paging.
* Readability is a primary concern.

<img src="./img/default-datalist.png" alt="Example of default spacing data list" width="990"/>

**Example:**
* You can see less data on one page.
* You will need a pagination to see more rows.
* Data structure includes many visual elements.

## Alternative solutions

Alternative to a data list include [tables](/components/table/design-guidelines) or [card views](/components/card/design-guidelines#card-views). Card views and data lists have similar properties, but information in a card view is chunked into a grid of individual cards. In choosing between a data list and a card view, consider the type of data that will be displayed and the format that best suits that data. If you cannot easily fit all of the data that needs to be displayed into a card, a data list might be a better solution.
Loading