|
| 1 | +--- |
| 2 | +name: Pickers |
| 3 | +keywords: |
| 4 | + - customer segments |
| 5 | + - locations |
| 6 | + - location picker |
| 7 | + - multiselect |
| 8 | + - multi-select |
| 9 | + - multi select |
| 10 | + - picker |
| 11 | + - resource picker |
| 12 | + - searchable listbox |
| 13 | + - searchable list |
| 14 | + - segment picker |
| 15 | + - segments |
| 16 | + - segementation |
| 17 | + - single select |
| 18 | +--- |
| 19 | + |
| 20 | +# Pickers |
| 21 | + |
| 22 | +Picking experiences present merchants with options to browse, find, and select from to perform an action. Pickers can help merchants navigate to a new page, filter an index table, or input one or more values in a form. |
| 23 | + |
| 24 | +--- |
| 25 | + |
| 26 | +## Best practices |
| 27 | + |
| 28 | +### Use progressive disclosure |
| 29 | + |
| 30 | +Introduce advanced features only when needed. Scale picker experiences consistently by establishing specific points for introducing functionality when merchants need them. Pickers should gradually offer more features as the number of options increases: |
| 31 | + |
| 32 | +- If there is only 1 option, there's no need to present it with a picker. The option value should be displayed directly in context, or not at all if it's not editable or relevant to completing an action merchants need to take on the page. |
| 33 | +- If there are only a small number of options, display all options in the picker. Sorting and filtering functionality is not needed for merchants to use the picker to complete an action on the page. |
| 34 | +- If there are a large number of options, merchants need filtering or sorting features in order to use the picker to complete an action. This is especially important if the action is repetitive, like tagging resources. |
| 35 | + |
| 36 | +### Sort with intention |
| 37 | + |
| 38 | +The order the options are sorted in should help merchants find and pick from the options quickly so they can focus on the action they need to take on the page. |
| 39 | + |
| 40 | +- Sort in the unique logical order relevant to the options the picker contains. [Date pickers](/components/date-picker) present options by month. [Color pickers](/components/color-picker) present options by hue. |
| 41 | +- Sort alphabetically if the picker contains text options that are most scannable by the content they contain, like customer names or locations. |
| 42 | +- Sort by most recently or frequently created, updated, or used if the picker contains options that were created in the context in which they are being picked, or are accessed or used repetitively. Products and collections benefit from being sorted by creation date, while customer segments are best sorted by date last edited. |
| 43 | + |
| 44 | +### Pin relevant options |
| 45 | + |
| 46 | +Pinning the most relevant options to the top of the picker helps merchants work through tasks quickly. Which and how many options are pinned depends on the action the picker helps merchants take. |
| 47 | + |
| 48 | +- If the picker presents merchants with navigation or filtering options, pin the main or most important option to the top. |
| 49 | +- If the purpose of the picker is to complete form input, pin the most frequently or recently used options to the top. |
| 50 | + |
| 51 | +## Picking resources |
| 52 | + |
| 53 | + |
| 54 | + |
| 55 | +The primary building block of resource picking experiences is the searchable listbox pattern. Searchable listboxes are composed of the [listbox](/components/listbox) and [text field](/components/text-field) components and can be displayed differently depending on what merchant problem you’re solving. |
| 56 | + |
| 57 | +The components are used directly inside of a container on the page if picking is part of the primary action merchants need to take, such as completing a form. The components may instead be hidden or revealed with an overlay, such as a popover or modal, to progressively disclose the list when merchants take an action on the page. Use progressive disclosure if the purpose of the picker is secondary to the action merchants should take on the page, such as navigation or list filtering. We'll look at the [customer segment picker](#customer-segments) and [location picker](#locations) for context specific implementation examples. |
| 58 | + |
| 59 | +### Locations |
| 60 | + |
| 61 | +The number of locations a merchant has can range dramatically, and the location experience should adapt to that number. Using progressive disclosure, we can introduce features as merchants need them. |
| 62 | + |
| 63 | +The location picker popover allows a merchant to select any location they have added in the admin. Location pickers are used as a filter the on the orders list and as a form input in logistics related features, like inventory transfers. |
| 64 | + |
| 65 | + |
| 66 | + |
| 67 | +#### 1 location |
| 68 | + |
| 69 | +When a merchant only has one location, the button that opens the location picker should be hidden. There’s no need to access the experience when they can’t switch locations. |
| 70 | + |
| 71 | + |
| 72 | + |
| 73 | +#### 2–10 locations |
| 74 | + |
| 75 | +When a merchant has 2–10 locations, show the button that accesses the location picker. The button always shows the current location. |
| 76 | + |
| 77 | +In the location picker: |
| 78 | + |
| 79 | +- Show “All locations” at the top of the list. |
| 80 | +- Make “All locations” the default selected location. |
| 81 | +- List all other locations in alphabetical order. Each location item shows the location name only. |
| 82 | + |
| 83 | + |
| 84 | + |
| 85 | +#### 11 or more locations |
| 86 | + |
| 87 | +When a merchant has 11 or more locations: |
| 88 | + |
| 89 | +- Apply the same features as 2–10 locations. |
| 90 | +- Add text search at the top of the location picker. This allows merchants to search for locations by specific criteria (location name, city, province, postal code, address, etc.). |
| 91 | +- Directly below the search, show a section with the 5 most recently used locations. If there are none, show the first 5 locations from the full list. |
| 92 | +- Below recently used locations, show an option to view all locations. Clicking this will show the inactive search state, displaying the full list of locations. |
| 93 | + |
| 94 | +### Customer segments |
| 95 | + |
| 96 | +Regardless of the scale of their business, merchants start with two default customer segments: "All customers" and "Customers who haven't purchased". The query builder at the top of the segment detail page can be used to filter customers and create new segments. Similar to the location picker, the customer segment picker introduces features only as merchants need them. |
| 97 | + |
| 98 | +The customer segment picker popover at the top of the segment detail page allows merchants to navigate to the detail pages of other segments. |
| 99 | + |
| 100 | + |
| 101 | + |
| 102 | +#### 1 - 10 segments |
| 103 | + |
| 104 | +When a merchant less than 11 segments, ... |
| 105 | + |
| 106 | + |
| 107 | + |
| 108 | +#### 11 or more segments |
| 109 | + |
| 110 | +When a merchant has 11 or more customer segments: |
| 111 | + |
| 112 | +- Apply the same features as 2–10 locations. |
| 113 | +- Add text search at the top of the location picker. This allows merchants to search for locations by specific criteria (location name, city, province, postal code, address, etc.). |
| 114 | +- Directly below the search, show a section with the 5 most recently used locations. If there are none, show the first 5 locations from the full list. |
| 115 | +- Below recently used locations, show an option to view all locations. Clicking this will show the inactive search state, displaying the full list of locations. |
| 116 | + |
| 117 | +### Implementation |
| 118 | + |
| 119 | +Something something searchable listbox. |
| 120 | + |
| 121 | +Something something segment picking for example |
| 122 | + |
| 123 | +Tabbed code examples |
0 commit comments