> 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/components/form/pickers.md). # Pickers Pickers allow users to select content from a set of values, usually presented in a list or dropdown menu.

## Overview Different types of pickers can be used in forms. Choosing the right picker depends on the type of answers requested and their number. ### Select `Select` is the most basic picker element. It lets the user select one item within a list of provided options. This component will be preferred for small lists (approx. 15 items) that do not require the specific features of `Async Select.` {% hint style="info" %} For 3 options or less, use RadioGroup component. {% endhint %} Within the Selection List, you may arrange options by bundles with title separators. Learn more about Selection List. We provide multiple features to custom the field, such as: `Label`, `Requirement Indicator` (Red Asterix), `Tooltip`, `Placeholder Value` and `Helptext`

**The placeholder value at its default state**

**How should I set my Select Component to its default state?** If there is one answer that seems more logical within all options, it would be a good practice to fill it as a pre-selected but overridable answer. * *Example: As a user, I want to set my platform language. On the settings page, the component* `Select` *is already set on the "English" value because it is the most preferred language in my company. But still, I can edit it if I need to.* However, if no options seem more logical as a default choice, it would be a better option to prefill with a "blank option" : `- - Select - -`. It will guide users to make their own choice. * *Example: As a user, I must fill in my personal information, including my civility. Because I did not provide any information about it beforehand, the field at its default state should remain empty with a placeholder.* **Note:** This blank option will not be considered a correct answer for a required field. If users try to save the form, the component will be in error state. Learn more about errors in forms ### Async Select

`Async Select` is a variation of `Select` component. It lets users select one item within a provided list of options. It has the same core design guideline. However, **this variant is specifically made for a long and/or complex list of options**. From a technical perspective, the options list will be recovered only when users open `Async Select` component. It means a potential loading state. Also, this component allows a partial loading of options which is a real comfort for technical performances. With this component, users can search for their answers in an integrated `Search Bar`. ### Multi Select

`Multi Select` is a form component that lets users select multiple items from a list. Users are not limited in the number of answers. On empty mode, `Multi Select` is distinguished by its "+" ("add") icon on the far right corner (rather than a dropdown arrow for a `Single Select`). `Selection List` opens in an overlay when the user clicks on the field. To each line, a checkbox + blue background appear when selected. Also, for each chosen line, a corresponding chip populates the field. `Selection List` stays open until users click on CTA "*Done*". {% hint style="info" %} If users click outside of `Selection List`, 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. With this component, users can search for their answers in an integrated `Search Bar` when the list has more than 20 items. When disabled with value, the picker shows all the selected values and cannot be collapsed. ### Async Multi Select

`Async Multi Select` is a variation of `Multi Select` component. It allows users to select multiple items within a list. It has the same core design guideline. However, **this variant is specifically made for a complex list of options**. Whether because of the large number of choices or because of long labels, etc ... With this component, users can search for their answers in an integrated `Search Bar`. Moreover, this component allows partial loading of the `Selection List` , which is a real comfort for technical performances. 💡To introduce the search bar, the placeholder text is "Search..." ### Time Picker

`Time Picker` is a `Select` component dedicated to time (hours & minutes). It can be distinguished from a `Select` by its "*Time*" icon on the far right corner of the field, but it has the same overall behavior. `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 ### Date Picker

`Date Picker` is the simplest dedicated component to let the user select **a date value**. With this picker, users can only select one day in the calendar (no range, no time). `Date Picker` is distinguished by its "calendar" icon on the far right corner of the field. Also, the `Placeholder` "*Select date*" helps users to understand they have to select a precise day. ⚠️ **Inputs are unwritable.** Users cannot enter a date manually. Choosing a date from the calendar is the only way to select a value. 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. *Timezone information appears automatically and only if the users' locale is different from the platform timezone.* 💡 A mobile version of the calendar is automatically displayed on small screens. ### 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`. Its only differences are the `Placeholder` text "*Select a period*" to help users understand they must select a period. Also, the calendar overlay shows two months in a row rather than only one for a `Date Picker`. It is possible to force a given time range, e.g. 4 days minimum. {% 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 %} ### 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.

### Inline advanced picker

\ The inline advanced picker triggers the advanced picker modal which is a key component to [advanced selection](/~/changes/DpgERwSwrKIthStzL4D6/patterns/advanced-selection.md). Once the items are selected, it displays a counter with "selected" as microcopy; you may override it. ## Accessibility `Label` is not mandatory, as we might need to overstack several pickers for a single label. However, this practice should be used sparingly with caution. It can be overwhelming or difficult for some people to understand how to fill an input without a label. We recommend defining a label adjacent to the field. In cases where we overstack several pickers for a single label, the gap between each field should be minimal (16px max). ## Key takeaways {% hint style="success" %} * Use placeholder to guide users in their selection * Think wise about the volume of items in the Selection List, should your component be Async. * Use predictable and logically ordered values * Always report to form patterns {% endhint %} {% hint style="danger" %} * Force an unlogical pre-selection as the default state * Use DateTimeRange for a single date * Consider providing less granularity when specifying minutes in a date picker. * Create new/custom behavior patterns with form components {% endhint %} ## Content #### Select Default text is always -- **Select** --. #### Async Select Default text is always -- **Select** --. Search placeholder text is always **Search**. #### Multi Select Primary CTA is always **Apply**. Secondary CTA is always **Cancel**.
#### Async Multi Select Default text is always -- **Select** --. Search placeholder text is always **Search**. Primary CTA is always **Apply**. Secondary CTA is always **Cancel**. #### Time Picker Placeholder text is always **Select time.**
#### Date Picker Placeholder text is always **Select date.** Primary CTA is always **Apply**. Secondary CTA is always **Cancel**.
#### Daterange Picker Placeholder text is always **Select period.** Primary CTA is always **Apply**. Secondary CTA is always **Cancel**.
#### DateTimerange Picker Placeholder text is always **Select period.** Primary CTA is always **Apply**. Secondary CTA is always **Cancel**. --- # 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/components/form/pickers.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.