# Displaying history

When it comes to displaying history on our platform, you can choose between two main components: **HistoryTable** and **Timeline**.

## **HistoryTable**

A **HistoryTable** is ideal for displaying detailed records of changes. It allows users to view not just the modifications themselves, but also key information about who made those changes, when they occurred, and what values were changed (before and after the modification).

<figure><img src="https://1297765105-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMoZPkWOmnKvoMWGW4aeM%2Fuploads%2F0M0aTISOHR3jNpVojTCX%2FHistory%20Table.png?alt=media&#x26;token=cb4d63ab-9d98-40c7-80fd-097ca274b5da" alt=""><figcaption></figcaption></figure>

**Key Features of a HistoryTable**:

* **Bundles of Changes**: Organizes changes into logical groups, helping users see sets of related modifications.
* **Who, When, What**: Provides clear visibility on who initiated the change and when, alongside a snapshot of the values before and after the change.
* **Audit-Ready**: Ideal for scenarios where tracking detailed records of all actions is crucial, especially for auditing purposes.

*Example*: Viewing a list of price updates for a product, with details on who made the change, what the old price was, and what it has been updated to.

{% hint style="info" %}
This pattern requires a combination of a datatable on a full page and a side drawer to display details.
{% endhint %}

## **Timeline**

A **Timeline** focuses on displaying the progression of an object over time. Instead of showing granular details of each change, it presents a high-level view of the object’s history, showing the key milestones in its lifecycle.

<figure><img src="https://1297765105-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMoZPkWOmnKvoMWGW4aeM%2Fuploads%2Ftv4MYqxFv0PxPwDTccBA%2FOrder-detail-seller.png?alt=media&#x26;token=6bea2844-a43b-4511-8cda-5056a1a6aef7" alt=""><figcaption></figcaption></figure>

**Key Features of a Timeline**:

* **Progressive View**: Visualizes the progression of an object through different stages or statuses.
* **Simplified History**: Instead of showing every single change, it highlights key events that mark significant points in the object's journey.
* **Narrative Flow**: Timelines are ideal when the goal is to understand how an object or entity evolved over time, rather than the specific details of each change.

*Example*: Viewing the status changes of an order, such as "created," "shipped," "delivered," with clear timestamps marking each transition.

{% hint style="info" %}
A timeline can be displayed either on a full page or within a side drawer.
{% endhint %}

{% hint style="info" %}
Timeline or Tasklist ?\
A **Timeline** shows the progression of an item, detailing past actions or upcoming events, while a [**Tasklist**](https://design.mirakl.com/design/components/actions/tasklist) helps users follow a process and take actions, focusing on tasks that need to be completed rather than reflecting past events.
{% endhint %}

## **HistoryTable or Timeline?**

When deciding between these two approaches, consider the following criteria:

| **Criteria**     | **HistoryTable**                                 | **Timeline**                                  |
| ---------------- | ------------------------------------------------ | --------------------------------------------- |
| Focus on detail  | Detailed view of changes (who, what, when)       | High-level overview of key events             |
| Data granularity | Shows bundles of changes and value modifications | Focuses on significant progression steps      |
| Use case         | Ideal for auditing or reviewing specific changes | Ideal for tracking the overall flow of events |
| Example          | Price updates, user action logs                  | Status progression of an order                |

Choose a **HistoryTable** when users need to dive deep into the specifics of each change, including before-and-after values and the actions taken by users. Opt for a **Timeline** when the goal is to give users a more narrative view of how an object has evolved over time, showing only the most critical events in its history.