# Empty state

## Overview The `Empty State` is a customizable component you can use when the real content is not available. It informs users why content is not shown or cannot be displayed. This component is a great help to create or maintain communication with users in various situations: error management, no results after a search, or no objects in a panel. The `Empty State` component is fully customizable; therefore, it has a large number of variants: * `Illustration`is **optional but highly recommended**; its size varies: "small", "medium" or "large". **Illustrations must convey the right message:** be mindful when choosing them. * `Title` (Heading/H2) is **mandatory.** Heading must be concise as it summarizes the situation. * `Subtitle` (Paragraph) is **optional.** It always needs to go with a title. Subtitles are meant to clarify the title and bring additional information if needed. Don't repeat the heading in paragraph text, and don't add a subtitle if it doesn't add any value. * `Action Button` is **optional**. \ Sometimes, user don't have anything to resolve the empty state, thus `Action Button` is not needed. \ But, in case users need to perform a specific action to resolve the Empty State, adding an `Action Button` help them understand what they need to do. \ If more than one action is available to resolve the situation, you can use a `Group Button`. The component takes over the expected content. As soon as an `Empty State` appears in a panel, there cannot be any other kind of content (text, title, datatable, etc.) in the same panel. {% hint style="success" %} **Do** Replace all content of a panel by Empty State Component {% endhint %}

Correct Empty State

{% hint style="danger" %} **Don’t**\ Mix Empty State component with actual content {% endhint %}

Incorrect Empty State

## Content An empty state shows users that the content they are looking for doesn't exist yet, preventing any kind of confusion. It‘s an opportunity to educate users towards their next action. We can also use it to highlight the benefit of a feature. An empty state should: * **Be clear:** To help users better understand what to do next. * **Give direction and educate the customer:** let users know what are the next steps. * **Be encouraging and inspire confidence:** use approachable copy and never make users feel unsuccessful or guilty because they see an empty state. If users land on a page they don't have permission to view, explain it clearly. ## **How to use** ### **First time on a feature** *When the user sees a feature for the first time, aka FTU (First Time Use).*

{% hint style="info" %} Title: \ {% endhint %} The description is here to explain what will happen when users start using this feature. {% hint style="info" %} Body: < Describe the first use case for this feature. Drive users to the next action to start seeing content here.> {% endhint %} The optional button can guide users towards the creation of a first object. ### Onboarding or configuration process *When the user sees a feature for the first time and is encouraged to take action.*

In this specific context, users must be encouraged to take action\ Title and description should be action-driven and describe what will be expected from the user. {% hint style="info" %} Title: \ \ \ or \ {% endhint %} {% hint style="info" %} Body: \ {% endhint %} ### Datatable or Datalist When a `Datatable` or a `Datalist` is empty, only display the toolbar + Pagination (all disable) and the empty state (medium size, not editable). \ Column titles, action buttons, etc., must be removed.

It's up to each project to decide if their empty `Datatable` / `Datalist` needs an action button to help users take action. \ The `Empty State Action Button` can differ from the `Datatable` / `Datalist Action Button` that will be displayed later on. ### No results *When users have searched for specific data, but no results match.* {% hint style="info" %} Automatically handled by ROMA for`Datatable` and `Datalist`. {% endhint %}

Content guideline : "No results found. Try different search term or update filters." Title and description should make it obvious that there are no results after searching for an item or filtering data and encourage users to check their search input and update filters. ### Error management *When the user faces network or generic technical issues preventing us from showing them the data they are looking for.* {% hint style="info" %} Automatically handled by ROMA for `Datatable` and `Datalist`. {% endhint %}

Content guideline : There was a problem \[**verb**]-ing \[**object**]. Refresh the page or try again later. Title and description should be clear and transparent on what is happening and if the user can do anything about it. ## **When not to use** Do not use empty states: * to display marketing information or feature promotion. * to display important contextual information covered by the [Alert](/design/components/feedback/alerts.md) component. ## Key takeaways {% hint style="success" %} * Choose the right illustration to convey the information * Add a [button](/design/components/actions/buttons.md) if it guides users through a process * Include a heading that summarizes the situation in a short sentence and add a subtitle if more explanation is needed {% endhint %} {% hint style="danger" %} * Forget to select an illustration * Add more than one button * Write long and complex headings and/or paragraphs. Use both elements to simplify mental load. {% endhint %}
--- # 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/components/feedback/empty-state.md?ask= ``` 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.