A filter picker allows users to choose one or more options from a searchable list.
Example
⌘ Cmd + ⌥ Option + 1
Properties
| property | propType | required | default | description |
|---|---|---|---|---|
| allEntities | [object] | custom | - | [] | Array of Objects or Immutable.List of Immutable.Maps of all entities, including selected ones |
| customFilterFn | func | - | () => null | Optional function that, if provided, can be used in place of the standard filter function. - Function will receive item, filterQuery, and contentToSearch arguments from a filter iterable, the last two values may be undefined so some sane defaults aren't a bad idea - Should return a boolean value, if null is returned by customFilterFn, the default filter function will be used instead - Example of a customFilterFn that behaves similarly to the default filter function: <FilterPicker customFilterFn={ (item, filterQuery = '', contentToSearch = '') => { return ( !item.get('archived') && contentToSearch.includes(filterQuery); ); } }> |
| keysToSearch | array | - | [ 'name', 'description' ] | Optional array of top level keys in allEntities to join and search for the filterQuery |
| selectedEntityIds | [number] | custom | - | [] | Optional array or Immutable.List of numbers of selected entity IDs. Do not provide if selected entities shouldn't be filtered from availableEntities |
| testSection | string | - | '' | String value for the outermost container's data-test-section attribute |
| children | func | yes | - | Function that should return a child node, passed an object as an argument with the following keys: - availableEntities {Array|Immutable.List}: The difference of allEntities and entities based on provided selectedEntityIds. Additionally, filtered via the default filter function based on the filterQuery value set in handleFilterInput, or alternatively a provided custom filter function - filterQuery {string}: Value stored in component state via handleFilterInput - handleFilterInput {Function}: Function that can be used in an input, that sets the input value in component state as filterQuery. This can be used for filtering in the default or custom filter function. If a search Input will be used with Blocklist and FilterList.ListItem, consider wrapping Blocklist inside a div with the oui-filter-picker-list class to remove the Input's bottom border (see story/story source for example) - selectedEntities {Array|Immutable.List}: Given the optionally provided selectedEntityIds, an array or Immutable.List of entities, based on ID, from allEntities |
Usage
Use a filter picker when user input requires searching lists of existing data like pages, audiences, metrics, etc. This complex component offers search, multiple selection, as well as optional view/delete/add buttons giving users a wide range of choices and UI elements.
Best Practices
Do
Filter the list contents as users type, if there is a long delay in the filter response time, present a Spinner
Don't
Avoid distracting users with too many subtasks like viewing or editing and focus on the main task