# Modal

<figure><img src="https://1297765105-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMoZPkWOmnKvoMWGW4aeM%2Fuploads%2FXd3ercdwcN6oqdZXTRQl%2FModal%20Hero.png?alt=media&#x26;token=5b23b026-6580-443d-a489-b98f990fd377" alt=""><figcaption></figcaption></figure>

### Guidelines <a href="#id-3358a3" id="id-3358a3"></a>

Use modal for the following purposes:

* **Users need to confirm an action** before they can continue with the main workflow. Only use modals for important steps in a workflow. While standard actions can be marked as skipped by users, confirmation of destructive actions is mandatory and can never be skipped.&#x20;
* **Add an item to a list** by creating it or selecting it from a list (see Advanced Picker
* **Create a simple object with limited information** using a maximum of 5 input fields. For complex forms, you should consider creating a dedicated page for that task.
* **Complete a task** without losing the current context of the page. Users won't be able to interact with the page until the modal is closed.

Modals come in 3 sizes: SMALL, MEDIUM, and LARGE. **SMALL should only be used for confirmation Modals.**

Modals should:

* Require that users take an action or cancel.
* Close when users press the `✕` button, the `Cancel` button, the `Esc` key, or when users click or tap the overlay outside the modal.
* Must have a primary action (the main purpose of the modal) and a secondary action (usually `Cancel`).
* Scroll if the content is larger than the max height of the container. The footer is sticky during scrolling so that the actions are always accessible by the user. Scrolling should be indicated by adding an additional drop shadow on the footer.&#x20;

\
Accessibility
-------------

* When a modal opens, focus moves automatically to the modal container so it can be accessed by keyboard users
* While the modal is open, a focus trap keyboard focus shouldn’t leave the modal
* Users can close the modal with the keyboard by activating the `✕` button, the `Cancel` button if one is provided, or by pressing the `Esc` key
* After a modal is closed, the focus returns to the button that opened it

\
Content
-------

Modals are composed of:

* A title
* A description
* One or several buttons

<figure><img src="https://1297765105-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMoZPkWOmnKvoMWGW4aeM%2Fuploads%2FRUcQ9NRonE8CCVhluzgB%2FModal%20Zoning.png?alt=media&#x26;token=973333e1-8d30-43b9-bbe4-7494bafec9aa" alt=""><figcaption></figcaption></figure>

### Title <a href="#id-9681e9" id="id-9681e9"></a>

The title states the outcome of an action and should explain clearly what a user is about to do, whether it's deleting a shop for a seller or a mapping configuration for an operator.

The title should be concise and clear and provide enough information for sellers and operators to make an informed choice. You can drop the a/an article.

Remember modals are disruptive and can be perceived as aggressive, so use them when necessary.

{% hint style="success" %}

* Generate new key
* Report as critical
  {% endhint %}

{% hint style="danger" %}

* Are you sure you want to generate a new key?
* Delete
  {% endhint %}

### Description <a href="#id-14eb22" id="id-14eb22"></a>

The description adds any valuable information that Mirakl users need to know in order to make an informed choice between the two action states in the buttons below. No questions.

{% hint style="success" %}
You're about to delete the entire product mapping configuration of the store. This cannot be undone.
{% endhint %}

{% hint style="danger" %}
Are you sure you want to delete the entire product mapping configuration of the store?
{% endhint %}

### Buttons <a href="#id-773c79" id="id-773c79"></a>

Buttons on modals should [follow generic button guidelines](https://mirakl.zeroheight.com/styleguide/s/42502/p/36c855-buttons/b/04e88d).

#### **Primary action**

Try to use the same language in the button as the action mentioned in the modal title.

{% hint style="success" %}
Title: Delete product mapping configuration

Button: Delete
{% endhint %}

{% hint style="danger" %}
Title: Delete product mapping configuration

Button: Confirm
{% endhint %}

Make the microcopy as precise as possible. Bear in mind users will potentially only read the title and the primary button of the modal.

#### **Secondary action**

The secondary action will most likely close the modal. Use common actions like Cancel or Close.

### Specific patterns <a href="#id-275e3c" id="id-275e3c"></a>

#### **Cancelation confirmation**

Cancellation confirmation modals can be tricky as "cancel" is the ultimate secondary action in modals. Here, it has to be the primary action.

You can indeed use "Cancel" as a primary action and clarify the secondary action as much as possible, "Keep \[verb-ing]" for example. The main objective is that the difference between the two actions is absolutely clear.

{% hint style="success" %}
Cancel + Keep editing

Cancel order + Keep order

Cancel order + Back to order
{% endhint %}

<br>


---

# 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/~/changes/DpgERwSwrKIthStzL4D6/components/overlays/modal.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.