# Pickers

{% hint style="info" %} This article is quite lengthy. To quickly find the information you're looking for, consider using the search. {% endhint %} ## Overview Different types of pickers can be used in forms. Choosing the right picker depends on the type of answers requested and their number. Here is an overview to assist you in choosing the appropriate picker based on your use case. For more in-depth information, please refer to the details of each picker.

Decision tree to choose which picker based on your use case

## Item Selection {% tabs %} {% tab title="Select" %}

`Select` is the simplest picker.\ Allows users to choose **one** item from a option list.\ To use for 'simple' option lists that do not require back-end calls to retrieve options (eg. list of countries, language...) {% hint style="danger" %} For 3 options or less, use [RadioGroup](https://design.mirakl.com/components/form/selection-controls#8185e8) component. {% endhint %} * Default Placeholder is manageable. [See Content Guideline](#default-placeholder-state-for-select) below. * Search bar is automatically shown for item lists with 20+ items * Group options into bundles with title separators to make it easier to read and understand. * Custom the field with optional props : `Label`, `Requirement Indicator` (Red Asterix), `Tooltip`, `Placeholder Value` and `Helptext` {% endtab %} {% tab title="Async Select" %}

`Async Select` is a variation of `Select` component. \ Allows users to choose **one** item from a option list.\ **This variant is specifically made for complex list of options that requires a back-end call (eg. list of brands, available options...)** `Async Select` loads options only when opened, which can result in a potential loading state before displaying the options. The component also supports partial loading for improved performance. * Default Placeholder is manageable. [See Content Guideline](#default-placeholder-state-for-select) below. * Search bar is automatically shown. * Group options into bundles with title separators to make it easier to read and understand. * Custom the field with optional props : `Label`, `Requirement Indicator` (Red Asterix), `Tooltip`, `Placeholder Value` and `Helptext` {% endtab %} {% tab title="Mutli Select" %}

`Multi Select` is a picker that offers more flexibility to the user.\ Allows users to choose **multiple items** from a list **without limitations**.\ To use for 'simple' option lists that do not require back-end calls to retrieve options (eg. list of countries, language...) When empty, `Multi Select` shows a '+' icon on the far right corner (unlike Single Select, which uses a dropdown arrow). The Selection List opens in an overlay, showing checkboxes and a blue background for selected items. Chosen items are represented by chips in the field. {% hint style="info" %} `Selection List` stays open until users click on CTA "*Done*". But if users click outside, the selection is still saved. {% endhint %} Users can unselect a value by clicking on the "x" ("remove") icon of its [chips](https://mirakl.zeroheight.com/styleguide/s/42502/p/310752-chips) or by unchecking the line in the `Selection List`. They can also clear the whole selection with the Secondary Button in the dropdown "*Clear*". Once the selection is made and the overlay is closed, the picker will only show **the first 8 values** (overridable setting) with chips. A " `Show More` / `Show Less` " action appears in the input to let users manage the overview. When disabled with value, the picker shows all the selected values and cannot be collapsed. {% endtab %} {% tab title="Async Multi Select" %}

`Async Multi Select` is a variation of `Multi Select.`\ Allows users to choose **multiple items** from a list **without limitations**.\ **This variant is specifically made for complex list of options that requires a back-end call (eg. list of brands, available options...)** Async Multi Select loads options only when opened, which can result in a potential loading state before displaying the options. The component also supports partial loading for improved performance. {% endtab %} {% endtabs %} ## Date/Time Selection {% tabs %} {% tab title="Time Picker" %}

`Time Picker` is a component dedicated to time (hours & minutes). \ With this picker, users can select **one item** in the calendar. When empty, `Time Picker` shows a 'time' icon on the far right corner (unlike Single Select, which uses a dropdown arrow). `Selection List items` of `Time Picker` are customizable : * 'interval' (from 1 to 60): allows populating options with precise interval * Removing time before the current time {% endtab %} {% tab title="Date Picker" %}

`Date Picker` is a component dedicated to dates (day). \ With this picker, users can select **one day** in the calendar. When empty, `Date Picker` shows a 'calendar' icon on the far right corner (unlike Single Select, which uses a dropdown arrow). When the user clicks the field, a calendar overlay appears with different actions and information (see below). The overlay is dismissed once one chooses a date. The chosen date populates the field. Users can always change the selected date or erase their selection by clicking on the "x" ("delete") icon. {% hint style="info" %} Timezone information appears automatically and only if the users' locale is different from the platform timezone. {% endhint %} {% hint style="info" %} A mobile version of the calendar is automatically displayed on small screens. {% endhint %} {% endtab %} {% tab title="Daterange Picker" %}

`Daterange Picker` is a variation `Date Picker` component. \ With this picker, users are invited to select **a period**, not only a single date. \ It has the same behaviors as `Date Picker`. The `Daterange Picker` differs from the `Date Picker` component in two ways: * The calendar overlay exhibits two consecutive months, as opposed to just one in the `Date Picker`. * The placeholder content is "Select a period" {% hint style="info" %} You have the option to enforce a specific time range. *eg. If a 4-day minimum range is enforced, users cannot select an end date earlier than 4 days from the chosen start date.* {% endhint %} {% hint style="warning" %} This component is made for users to select a range with **two different values (a start date and an end date)**. While it's still possible to select the same value for both (ending with users selecting a range of a unique day), this behavior should not be encouraged. {% endhint %} {% endtab %} {% tab title="DateTimerange Picker" %}

`DateTimerange Picker` is the most complete version of pickers dedicated to dates and times. \ It allows users to select a date range and to associate a precise time of the day. \ Time selection is optional.

Unlike other pickers and because of its complexity, `DateTimerange Picker` overlay opens in a modal when the user clicks on the field. {% endtab %} {% endtabs %} ## Inline advanced picker

\ The inline advanced picker triggers the advanced picker modal which is a key component to [advanced selection](https://design.mirakl.com/design/patterns/advanced-selection). Once the items are selected, it displays a counter with "selected" as microcopy; you may override it. ## Layout For a clear form layout, follow these simple design rules: * Place inputs in a vertical sequence, each stretching across the full panel width for a clean look. * If you're aligning inputs side-by-side, leave a 16px gap between them to prevent clutter. * Similarly, when stacking inputs vertically under a single label, keep a 16px space for clear separation. ## Content ### Label Use a noun, no preposition, no action verb. {% hint style="info" %} Template: \ {% endhint %} ### Default Placeholder State for Select {% hint style="info" %} Template: - - Select - - or \ {% endhint %}

How to choose the right placeholder

When a clear and logical default choice is evident, pre-select it, while also allowing users the option to override it. \ For example, in language selection, 'English' is initially chosen but can be modified by the user. \ In such instances, we recommend informing the user this default choice was made on their behalf by explicitly marking it as the 'default' selection.\ In this scenario, the component will always have a value, eliminating the possibility of it being null, and consequently, the picker will never be in an error state. This approach obviates the need to designate the picker as 'mandatory' to avoid rendering an ineffectual verification step. When no option presents a clear logical choice, employ a 'blank option,' such as **'- - Select - -'**, to guide users in making their decision. \ It's important to note that the 'blank option' is not a valid response for required fields and will result in an error if users attempt to save the form with this selection.\ In this scenario, the component can be clearly stated as mandatory.

exemple of two placeholder content for picker

### Help text Prefer a help text over a tooltip to add extra details, and explain how to fill the field or its purpose. If you are just repeating yourself, don’t use a help text. {% hint style="info" %} Template: \ {% endhint %} ### Tooltip Tooltip appears when hovering the ? icon or a disabled button. They are not used to communicate critical information but to provide additional information. {% hint style="info" %} Template: \ {% endhint %} ## Key takeaways {% hint style="success" %} **Do** * Consider whether to display a default value or prompt users to select one when using a picker component * Asynchronous components are meant for complex selection lists. * Use predictable and logically ordered values * Always report to form patterns {% endhint %} {% hint style="danger" %} **Don't** * Avoid imposing an illogical pre-selection as the default state * Use DateTimeRange for a single date, even if it's technically possible * Consider providing less granularity when specifying minutes in a date picker. * Create new/custom behavior patterns with form components {% endhint %}