# 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="/files/eKT1ONnWFkDzm6F7dYq0" 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="/files/895qK8SuAC5VZZaLBbBK" 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**](/design/components/actions/tasklist.md) 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://design.mirakl.com/design/patterns/displaying-history.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.