# Multi-Select Picker The Multi-Select Picker lets users pick multiple items from a data-bound list inside a clean modal dialog. Selected items appear as removable chips on the trigger button, and the component outputs a comma-separated list of IDs and labels that you can pipe directly into other actions -- perfect for tagging, category selection, permission assignment, and any scenario where a user needs to choose more than one thing at a time. ## Getting Started Add the component to a screen and connect a collection to the **Items** prop. Set **Item Label** to the field you want displayed (e.g. the record's Name field). The component is ready to use immediately -- tapping the trigger opens the picker modal, and selections appear as chips. ## Settings ### Items The collection the picker pulls its list from. Connect any Adalo collection or filtered list here. ### Item Label The field from each record displayed as the row label inside the picker and as the chip text after selection. Use Magic Text bound to a text field in your collection. ### Placeholder Text Text shown on the trigger button when nothing is selected yet. (default: `Select...`) ### Show Search Toggles the search bar inside the picker modal. When on, users can filter the list by typing. (default: on) ### Max Selections (0 = unlimited) Sets an upper limit on how many items a user can select at once. Once the limit is reached, unselected rows are dimmed and can't be tapped. Set it to `0` for no limit. (default: `0`) ### Pre-Selected IDs (comma-separated) Populate this with a comma-separated string of record IDs to pre-check items when the picker opens. Useful for edit screens where you want to restore a user's previous choices. Use Magic Text or a database field that stores the ID string. ### When Selection Changes An action that fires every time the user checks or unchecks an item. Receives two Magic Text values: * **Selected Labels** -- comma-separated display names of all currently selected items * **Selected IDs** -- comma-separated record IDs of all currently selected items ### Style → Accent Color Color used for checked checkbox fills, the "Done" button, and focus states. (default: iOS blue `#007AFF`) ### Style → Background Color Background color of the trigger button and the picker modal. (default: white) ### Style → Border Color Color of the trigger button border, search input border, and row dividers. (default: `#dddddd`) ### Style → Border Radius Corner radius of the trigger button. The picker modal always uses rounded corners. (default: `8`) ### Style → Text Color Color for item labels, header title, and selected item text. (default: near-black `#111111`) ### Style → Placeholder Color Color for the placeholder text on the trigger and the "Search..." hint inside the picker. (default: `#aaaaaa`) ### Style → Font Size Base font size for all text in the component. Header title is 2px larger. (default: `14`) ### Style → Chip Background Fill color of the selected-item chips shown on the trigger button. (default: light blue `#e8f0fe`) ### Style → Chip Text Color Text and × icon color inside the chips. (default: `#1a73e8`) ## Actions ### On Item Selected Fires on the individual item when a user checks it. Attach database actions here to create a relationship record (e.g. create a UserTag linking the current user to the selected item). The action has access to the item's own Magic Text fields. ### On Item Deselected Fires on the individual item when a user unchecks it. Attach database actions here to delete the corresponding relationship record. ### When Selection Changes Fires after every check/uncheck with the full current selection as Magic Text. Use this to update a text field on a record with the comma-separated IDs or labels. ## Tips & Best Practices * **Use Pre-Selected IDs on edit screens** -- store the comma-separated ID string in your database and bind it to Pre-Selected IDs so the picker restores previous choices when the screen opens. * **Pair On Item Selected / On Item Deselected with relationship collections** -- create a join collection (e.g. UserCategories with a User relationship and a Category relationship) and use these actions to add/remove records in real time. * **Use When Selection Changes to save the full selection** -- if you need a single field storing all choices, update a text property on a record with the Selected IDs Magic Text output from this action. * **No Formatting on Magic Text IDs** -- when binding record IDs to Pre-Selected IDs, always use the No Formatting option in the Magic Text picker to avoid extra characters. * **Set Max Selections for constrained choices** -- for things like "pick up to 3 interests," set Max Selections to `3`. The component automatically disables unchosen rows once the limit is hit. * **Show Search is most useful with long lists** -- for lists under \~10 items, consider turning it off to keep the picker clean. * **Select all / Deselect all applies to search results** -- when the user has typed a search query, Select all and Deselect all only affect the filtered rows, not the entire list. ## Example Use Cases **Interest tagging on a profile setup screen** -- Connect a Topics collection, bind Item Label to the topic name, set Max Selections to 5, and use When Selection Changes to save the Selected IDs string to the user's profile. **Multi-category product filter** -- Place the component in a filter panel. Bind to a Categories collection and use the Selected IDs Magic Text output to filter a product list on the same screen. **Team member assignment** -- Connect a Users collection filtered to your workspace. Use On Item Selected to create a ProjectMember record and On Item Deselected to delete it. **Permission role selector** -- Bind to a Roles collection, pre-populate with the user's existing roles via Pre-Selected IDs, and save changes back on form submit using the Selected IDs output. **Event tag picker** -- On an event creation form, let organizers tag an event with multiple topics. Save the comma-separated label string directly into a text field for display elsewhere in the app. --- # 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://help.adalo.com/component-basics/marketplace-components/multi-select-picker.md?ask= ``` 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.