> For the complete documentation index, see [llms.txt](https://design.mirakl.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://design.mirakl.com/~/changes/DpgERwSwrKIthStzL4D6/patterns/forms/stepper-and-onboarding-stepper.md). # Stepper and onboarding stepper ## Stepper

### Overview `Stepper` is designed to help users create any complex item within Mirakl in a simple way. `Stepper` should be used: * For standard, sequenced experiences * For complex item creation `Stepper` should not be used: * For onboarding experiences. Use the [Onboarding stepper ](#onboarding-stepper)instead. {% hint style="danger" %} Never add an illustration to a stepper. Use the [Onboarding stepper ](#onboarding-stepper)instead. {% endhint %} ### Guidelines #### One topic at a time Do not confuse users with mixed topics within a single step; keep one idea per screen. #### Fields must be easy to fill Users must fill in their form quickly to secure their arrival on Mirakl. Use standard form components such as [fields](/~/changes/DpgERwSwrKIthStzL4D6/components/form/fields.md), [select](/~/changes/DpgERwSwrKIthStzL4D6/components/form/selection-controls.md) options, [checkboxes](/~/changes/DpgERwSwrKIthStzL4D6/components/form/selection-controls.md#41d3fe-1), etc. #### Provide enough context and guidance 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. ### Structure #### Progress steps

Bar with validation steps, only usable within the stepper component

* Keep labels short and consistent (nouns for all steps, actions for all steps). * Each step is clickable. Learn more about how [error management](#0900f2) works for the progress steps. #### Savebar Savebar actions are standardized. * One [button group](/~/changes/DpgERwSwrKIthStzL4D6/components/actions/button-group.md) with Back + Continue actions * A third Save as draft action can be created depending on project needs, but it is not an off-the-shelf feature. To exit the stepper, the user can click the “Back to” link + will get a "prompt before you leave" modal. When the user clicks the Primary button on the last step of the Stepper, the Async button gets a Loading status. ### Error management Errors are managed automatically by Roma. Users know there are errors as the **progress steps** relevant steps change color. * 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. The user can then navigate between the steps to solve their errors.

An [alert](/~/changes/DpgERwSwrKIthStzL4D6/components/feedback/alerts.md) appears with all the errors from the current step. When the errors are fixed, the user must save the step. If they don’t and click on the progress steps component, they will get a "prompt before you leave" modal.

\ Onboarding stepper ------------------

The onboarding stepper is dedicated to onboarding experiences for new users. Its simple design helps users provide key information quickly and seamlessly. ### Overview 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](#stepper) instead. {% hint style="danger" %} Do not use a datatable within the onboarding layout. {% endhint %} ### Guidelines #### One topic at a time Do not confuse users with mixed topics within a single step; keep one idea per screen. #### Mind the number and length of steps 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 Users must fill in their form quickly to secure their arrival on Mirakl. Use standard form components such as [fields](/~/changes/DpgERwSwrKIthStzL4D6/components/form/fields.md), [select](/~/changes/DpgERwSwrKIthStzL4D6/components/form/selection-controls.md) options, [checkboxes](/~/changes/DpgERwSwrKIthStzL4D6/components/form/selection-controls.md#41d3fe-1), etc. #### Provide enough context and guidance 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.
### Structure The onboarding stepper is made of: * On one side, an illustration picked from the Mirakl library that must be relevant to the overall theme of the form

Illustrations fitting the onboarding stepper

* On the 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)
You may add an [activity loader](/~/changes/DpgERwSwrKIthStzL4D6/components/feedback/activity-loader.md) at the end of your onboarding stepper. ### Error management Errors are managed automatically by Roma. * 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.

--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## 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, and the optional `goal` query parameter: ``` GET https://design.mirakl.com/~/changes/DpgERwSwrKIthStzL4D6/patterns/forms/stepper-and-onboarding-stepper.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.