# Datatable

{% hint style="info" %}
This article is quite lengthy. To quickly find the information you're looking for, consider using the intelligent search.
{% endhint %}

## **Overview**

**Datatables are a core component of our products**, designed to present information in a structured grid format with rows and columns. This format simplifies data comprehension and helps users in managing their content

Datatable should be used:

* to display complex data in an easy-to-scan way,
* if users need to sort on multiple columns,
* if users need column titles to make sure the context and content are clear,
* if data needs to be displayed in a controlled way (using pre-formatted cells).

Datatable should not be used:

* To display a collection of items with an elaborate layout (use [Datalist](https://design.mirakl.com/design/components/datalist)),
* To highlight part of a data set (use **Data Visualization**).
* If data is not structured or with variable content

{% hint style="info" %}
Having trouble deciding between Datalist and Datatable? \
Head over to the [Displaying data pattern](https://design.mirakl.com/design/patterns/displaying-data)
{% endhint %}

## Design Guidelines

<figure><img src="https://zeroheight.com/uploads/Ji6IMJUe308Dek1fFnakHg.png" alt=""><figcaption></figcaption></figure>

1\. **Title&#x20;*****:*** clearly states the content of the datatable.&#x20;

{% hint style="info" %}
For further details on each listed element, please refer to the dedicated subpage.
{% endhint %}

2\. **Toolbar**

3\. **Columns**

4\. **Rows**

5\. **Scrollbar**

6\. **Footer and pagination**

{% tabs %}
{% tab title="Toolbar" %}
The toolbar includes a search bar, filters, and options for managing displays and adding content.\
Available elements include:

* Search (standard or column-specific with a drop-down selector)
* **Item count (mandatory)**
* Column management
* **Density management (mandatory)**
* Export (only on visible data)
* Action button
* Refresh (disabled while reordering)
* Filters

For 3 or fewer filters, use the Quick Filters layout. For more than 3 filters, use the Filters Drawer, which opens on the right side of the screen.

<figure><img src="https://zeroheight.com/uploads/O5pGcYKbYrxQLfrdzQsNZQ.png" alt=""><figcaption></figcaption></figure>
{% endtab %}

{% tab title="Columns" %}

<figure><img src="https://1297765105-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMoZPkWOmnKvoMWGW4aeM%2Fuploads%2F8Y8rT1B5PhTjuTQH43cq%2FjbBkohyFYU5_EYmC7cBOfA.gif?alt=media&#x26;token=584a27ad-453f-4e01-9dd8-f2f11f3f280a" alt=""><figcaption></figcaption></figure>

Column width is defined by the largest content (cell and header) within a limit of 500 px. The width is overridable. Otherwise, the content is cut with an ellipsis.

**Datatables are sorted by default.** Feature teams define which column is used to sort the datatable. It can be sorted by identifier, by date/time, by status...\
The sort must be visible, on the left side, to help users understand how data is sorted.

* **At least one column must provide a sortable property**.
* Sortable properties are exclusive. It means if two or more columns provide a sortable property, they can not be active at the same time.
* Sort property can only be deactivated when search is active. When user type for an item in the search bar, sort is not mandatory.
  {% endtab %}

{% tab title="Rows" %}
A row displays information related to a single item.

#### Row States :

<figure><img src="https://1297765105-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMoZPkWOmnKvoMWGW4aeM%2Fuploads%2FAWntCI0wnTZ6Gbh8LMu3%2FRow%20type.png?alt=media&#x26;token=ddb2b4ab-8bf8-459a-bd67-abaead51ed2a" alt=""><figcaption></figcaption></figure>

* **Default:** row is clear, and actions are available. This is the standard row behavior.
* **Disabled:** row is greyed out, and actions are unavailable. For example, you may use it when a product is rejected, and no action can be taken to change its status.
* **Highlighted:** row has a ribbon to highlight it
* **Dimmed:** row is greyed out, but actions are still available. For example, you may use it when a product has been excluded from a selection, but you can reactivate it later.

#### Rows Types

<figure><img src="https://1297765105-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMoZPkWOmnKvoMWGW4aeM%2Fuploads%2FtLCrUg5LK5eJcUNbLEIa%2FRow%20type.png?alt=media&#x26;token=062b7d20-c050-44cd-acb4-9737bf127582" alt=""><figcaption></figcaption></figure>

* **Selection :** rows are selectable and selection is managed with the bulk.
* **Reorder:** rows can be reordered by user action. \
  The drag functionality is shown but disabled when the table contains only a single row.

{% hint style="info" %}
In our products, we commonly utilize the 'reorder' datatable type to prioritize custom rules based on their importance. \
It's essential to remind users, in such scenarios, their rules will be processed by their ranking.
{% endhint %}

{% hint style="warning" %}
When using the reorder function, datatable cannot have pagination.
{% endhint %}

#### Rows Size

<figure><img src="https://zeroheight.com/uploads/Cx-HI01kPFSIhkDnX1SqGA.png" alt=""><figcaption></figcaption></figure>

Rows are available in three sizes: *compact*, *default* (used by default), and *comfortable*. Users can change size with the density button in the filter bar. This option is automatically handled.
{% endtab %}

{% tab title="Cells" %}
They are 9 Cell Types for Datatables :

**1. TextCellContent**

* **Description**: Displays text with optional subtext, media, actions, and a trailing icon for tooltips.
* **Options**:

  * **Sizes**: Default / Comfortable / Compact
  * **Actions**: No action, expandable, view, edit, or external link.
  * **Media**: Available for Default and Comfortable sizes.

  <figure><img src="https://1297765105-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMoZPkWOmnKvoMWGW4aeM%2Fuploads%2FPwksWAip5g5Gc7ref9XZ%2FCapture%20d%E2%80%99e%CC%81cran%202024-09-18%20a%CC%80%2015.44.28.png?alt=media&#x26;token=e8d010f7-d16e-4f40-9a94-7ca017df69c8" alt="" width="159"><figcaption><p>TextCellContent</p></figcaption></figure>

**2. BadgeCellContent**

* **Description**: Displays up to 3 badges, each with an optional tooltip. More than 3 badges are expandable.
* **Options**:
  * **Statuses**: Custom badge statuses.

<figure><img src="https://1297765105-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMoZPkWOmnKvoMWGW4aeM%2Fuploads%2FR5jLsTjWg6KXvm8MThGv%2FCapture%20d%E2%80%99e%CC%81cran%202024-09-18%20a%CC%80%2015.46.22.png?alt=media&#x26;token=10eb83e8-19d5-4ace-8c25-1294bd561805" alt=""><figcaption><p>BadgeCellContent</p></figcaption></figure>

**3. DateCellContent**

* **Description**: Displays dates with optional subtext, statuses, and a trailing icon for additional information (e.g., late, help).
* **Options**:
  * Expandable, subtext, trailing icon, and statuses.

<figure><img src="https://1297765105-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMoZPkWOmnKvoMWGW4aeM%2Fuploads%2FpGYIBdgD47Yk1uJn77yu%2FCapture%20d%E2%80%99e%CC%81cran%202024-09-18%20a%CC%80%2015.46.59.png?alt=media&#x26;token=5376697f-cc2b-4540-bda2-835e6d28afd6" alt=""><figcaption><p>DateCellContent</p></figcaption></figure>

**4. IconListCellContent**

* **Description**: Displays a list of icons, each with a name, status, and automatic tooltip.
* **Options**:
  * **Icon Statuses**: Pending (purple), Warning (orange), Error (red), Success (green), Default (grey).
  * Icons should never be empty; use disabled status if needed.

<figure><img src="https://1297765105-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMoZPkWOmnKvoMWGW4aeM%2Fuploads%2FXOM2D79q5HQcfZCq0zUv%2FCapture%20d%E2%80%99e%CC%81cran%202024-09-18%20a%CC%80%2015.48.55.png?alt=media&#x26;token=84d01a3c-bd52-4f45-b05a-c8a35b1b4b61" alt=""><figcaption><p>IconListCellContent</p></figcaption></figure>

**5. MonetaryCellContent**

* **Description**: Displays numeric monetary values, aligned to the right.
* **Options**:
  * Expandable or edit actions, optional subtext, icons, and various statuses.
  * Currency symbol can be placed before or after the number.

<figure><img src="https://1297765105-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMoZPkWOmnKvoMWGW4aeM%2Fuploads%2FUzXub141F8ystPI9vA0J%2FCapture%20d%E2%80%99e%CC%81cran%202024-09-18%20a%CC%80%2015.50.22.png?alt=media&#x26;token=fe9d0d74-ab67-4054-bbd4-7045023d3550" alt=""><figcaption><p>MonetaryCellContent</p></figcaption></figure>

**6. NumericCellContent**

* **Description**: Displays numeric content (non-currency), aligned to the right.
* All numeric content HAVE to be displayed with this cell type ; not as paragraph
* **Options**:
  * Same options as MonetaryCellContent but without the currency symbol.

**7. ParagraphCellContent**

* **Description**: Displays a paragraph with automatic truncation to 2 lines.
* **Options**:
  * No statuses, subtext, or actions; solely for displaying long text.

<figure><img src="https://1297765105-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMoZPkWOmnKvoMWGW4aeM%2Fuploads%2F22SLRVxNQTGSRo47LGrx%2FCapture%20d%E2%80%99e%CC%81cran%202024-09-18%20a%CC%80%2015.52.44.png?alt=media&#x26;token=fb1cef28-abef-46fb-8093-1a43ecfa5b74" alt=""><figcaption><p>ParagraphCellContent</p></figcaption></figure>

**8. RatingCellContent**

* **Description**: Displays rating content with optional subtext, expandable action, or tooltip.
* **Options**:
  * **Variants**: Rating with stars or numeric text-only.
  * Same statuses as TextCellContent.

<figure><img src="https://1297765105-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMoZPkWOmnKvoMWGW4aeM%2Fuploads%2FrieHp1xnbdxG5VwlZySn%2FCapture%20d%E2%80%99e%CC%81cran%202024-09-18%20a%CC%80%2015.53.40.png?alt=media&#x26;token=8645d3d8-5169-4498-8cca-3e36a8729e33" alt=""><figcaption><p>RatingCellContent</p></figcaption></figure>

**9. StatusCellContent**

* **Description**: Displays a single status with optional tooltip.
* **Options**:
  * **Icon Statuses**: Pending (purple), Warning (orange), Error (red), Success (green), Default (grey).
  * Can be expandable.

<figure><img src="https://1297765105-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMoZPkWOmnKvoMWGW4aeM%2Fuploads%2Fq0hLrQqFlsEVdsAOkGcD%2FCapture%20d%E2%80%99e%CC%81cran%202024-09-18%20a%CC%80%2015.54.12.png?alt=media&#x26;token=819ecee1-dd15-454c-9a67-00df7e2b910b" alt=""><figcaption><p>StatusCellContent</p></figcaption></figure>
{% endtab %}

{% tab title="Footer & pagination" %}
On Datatable's footer, users can manage pagination :&#x20;

* Manage number of items per page
* Navigate through the pages

Each project has the flexibility to set its own pagination thresholds, which should be determined based on the average number of results.&#x20;

**We recommend using thresholds of 50, 100, and 200 items per page.**&#x20;

If your datatable is expected to display a smaller number of items, you can opt for lower thresholds.

**Navigation elements are consistently visible on the datatable.**&#x20;

* In cases where the current page corresponds to either the first or last page, the pagination controls are displayed, but the navigation buttons are disabled.
* In cases where the current number of item is lower than the first threshold, the pagination controls are displayed, but the navigation buttons are disabled.

When your Datatable contains a significant amount of data, such as more than 1,234 results, we display a universally formatted number, typically around +1,000.&#x20;
{% endtab %}
{% endtabs %}

## Behaviors & Interactions <a href="#id-912e88" id="id-912e88"></a>

The datatable allows users to:

* Sort by column headers
* Filter data subsets
* Perform single or bulk actions
* Export data in various formats
* Add or reorder data
* Navigate via pagination

### Default item

In a datatable, **only one item can be designated as the 'default.**'&#x20;

'Default' status is designed with a simple "Default" mark inlined with the Label of the cell.

### Expand cells <a href="#id-55a556" id="id-55a556"></a>

Cells may contain extensive or highly detailed information that could potentially overwhelm the datatable's presentation. But also, opening a separate detailed page might appear excessive. To strike a balance, we have introduced 'expand' properties for select cells.

<figure><img src="https://1297765105-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMoZPkWOmnKvoMWGW4aeM%2Fuploads%2FsO1TdbTMUbpq3sGcIwnp%2FEnregistrement-de-l%E2%80%99e%CC%81cran-2023-09-14-a%CC%80-11.27.35.gif?alt=media&#x26;token=0a407f3a-1039-48d3-9498-da98da63f53e" alt="" width="375"><figcaption></figcaption></figure>

Expandable cells are recognized with a chevron. Extra content is displayed in a [popover ](https://design.mirakl.com/design/components/overlays/popover)cell. Content can be structured and with a button if needed.

### **Actions on a Datatable**

Datatables support bulk and individual actions, with varied behavior based on user interactions.&#x20;

To get more details about a row, the first cell ("TextCellContent") must have either the "view" action (open object) or "external link" action (open in a new window). In these cases, the first action in the [action menu](https://design.mirakl.com/design/components/actions/action-menu) should always be "View Details."

Below are listed all ways we design action, wether its individual or bulk actions :

#### Individual action <a href="#id-55a556" id="id-55a556"></a>

<figure><img src="https://1297765105-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMoZPkWOmnKvoMWGW4aeM%2Fuploads%2FzI6VUt09uvYBsZWB8K0Z%2Factions.svg?alt=media&#x26;token=072818bb-ba1e-43cb-be37-eec89a06e2d3" alt="" width="563"><figcaption></figcaption></figure>

Individual quick actions for a single row are available to users, these actions are consistently presented at the end of the row. Three options are available :

* Actions displayed as icon buttons for common actions such as Download, Delete, View, Copy, etc. (**Must be IconButton in Secondary Variant**)
* Actions displayed as secondary buttons for less common actions that may not be easily understood through icons. (**Must be Button in Secondary Variant**)
* Actions accessible via an action menu for multiple choice of actions.

#### Bulk actions <a href="#id-55a556" id="id-55a556"></a>

<figure><img src="https://zeroheight.com/uploads/OBbe54yh_0bZR_Qwk5AXAg.png" alt=""><figcaption></figcaption></figure>

Datatable enables users to select individual rows or multiple rows for performing actions.&#x20;

Once selected, a bulk action bar will appear, offering a single action (primary button) or more action options ([button group](https://design.mirakl.com/design/components/actions/button-group)). \
Actions listed on the bulk bar actions must always remain the same ; they cannot change based on the selection or filters.

The selection bar allows to quickly select all items in the dataset, all items on the current page, or to deselect all items. However, once all items are selected in a datatable through this option, individual deselection is not possible.

<figure><img src="https://1297765105-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMoZPkWOmnKvoMWGW4aeM%2Fuploads%2FdKl0BxjjOpwjFXhH7F7A%2FDatatable%20Bulk%20Actions.png?alt=media&#x26;token=f5c9e55b-5fff-4cb2-aba5-a0d02ef01cf4" alt=""><figcaption></figcaption></figure>

Users can select all elements in a filtered dataset by first applying a filter to the data and then using the 'select all from this page' option.

### Scrolling <a href="#id-440909" id="id-440909"></a>

#### **Horizontal**

When the content of a row is longer than the width of the panel, a floating trailing action is displayed. It ensures the user can perform an action on a row without scrolling.

<figure><img src="https://zeroheight.com/uploads/HCal3YzGWKekAHmEjqDPjw.png" alt=""><figcaption></figcaption></figure>

#### **Fixed header**

The column header is pinned while scrolling to ensure the readability of the cell content. The horizontal scrollbar is pinned to the bottom of the viewport to ensure it will always be visible and easily reached.

<figure><img src="https://zeroheight.com/uploads/-4EJDs9ScODQ8y3CyetSuA.gif" alt=""><figcaption></figcaption></figure>

### Loading <a href="#id-8584ed" id="id-8584ed"></a>

When datatable's items are loading :

<figure><img src="https://zeroheight.com/uploads/xDNAknv5Sd-Kf8LIMbEHqw.gif" alt=""><figcaption></figcaption></figure>

Skeleton loading is fully automated for `Datatable.` [Learn more about Loading patterns](https://design.mirakl.com/design/patterns/loading)

### Empty state <a href="#id-978cb3" id="id-978cb3"></a>

Empty state behavior and microcopy are automatically handled.&#x20;

Content for any other type of empty state has to be defined for each project.&#x20;

The toolbar (with the options you chose to add) is displayed in disabled mode, and the primary action is disabled. The same action is moved to the empty state.

<figure><img src="https://zeroheight.com/uploads/yQyl3qSoB0NsrXTWieC4HQ.jpg" alt=""><figcaption></figcaption></figure>

The empty state action is the same as the toolbar's, but you may override it. \
[Learn more about writing empty states](https://design.mirakl.com/design/components/feedback/empty-state)