# Onboarding form

<figure><img src="/files/Sy3rTN7fVN0y9HnJUDJv" alt=""><figcaption></figcaption></figure>

### Overview <a href="#id-88f3d7" id="id-88f3d7"></a>

Within Mirakl, the onboarding stepper should be used:

* When a user is setting up an account for the first time
* When a user is setting up an organization for the first time
* When a seller is creating a store

The onboarding stepper shouldn’t be used:

* For standard, sequenced experiences. Use [Stepper form](/design/patterns/forms/stepper-form.md) instead.

{% hint style="danger" %}
Do not use a datatable within the onboarding layout.
{% endhint %}

### Guidelines <a href="#id-78d80a" id="id-78d80a"></a>

#### One topic at a time <a href="#id-72394a" id="id-72394a"></a>

Do not confuse users with mixed topics within a single step; keep one idea per screen.

#### Mind the number and length of steps <a href="#id-354610" id="id-354610"></a>

When asking Mirakl users for information, keep the number of steps to an amount users are able to take in (4 or 5).

#### Fields must be easy to fill <a href="#id-565377" id="id-565377"></a>

Users must fill in their form quickly to secure their arrival on Mirakl. Use standard form components such as [fields](/design/components/form/fields.md), [select](/design/components/form/selection-controls.md) options, [checkboxes](/design/components/form/selection-controls.md#41d3fe-1), etc.

#### Provide enough context and guidance <a href="#id-267a91" id="id-267a91"></a>

Users need to understand why we're asking for specific information and how we will use that information. Add context and guidance to make the user feel confident.<br>

### Structure <a href="#id-3536b9" id="id-3536b9"></a>

The onboarding stepper is made of:

* On the right side, an [illustration picked from the Mirakl library](/design/components/images/illustrations.md) that must be relevant to the overall theme of the form

<figure><img src="https://zeroheight.com/uploads/6Eh5SiVWUXWIr33SQp8XZg.png" alt="" width="375"><figcaption><p>Illustrations fitting the onboarding stepper</p></figcaption></figure>

* On the left other side, a form with:
  * A logo (optional + can be changed at each step of the form)
  * A title
  * A progress bar
  * Form fields
  * Save/Cancel button group

The onboarding stepper has 2 save modes:

* in memory (when the last step is approved)
* in the database (save at the end of each step)<br>

You may add an [activity loader](/design/components/feedback/activity-loader.md) at the end of your onboarding stepper.

### Error management <a href="#id-50bdd1" id="id-50bdd1"></a>

{% hint style="info" %}
Errors are managed automatically by Roma.&#x20;
{% endhint %}

* If there are errors within one step of the stepper, the user is automatically redirected to the relevant step.
* If there are errors within several steps of the stepper, the user is redirected to the first step where there’s an error.

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


---

# 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/forms/onboarding-form.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.