{"id":13450820,"url":"https://github.com/jschloer/use-multiselect","last_synced_at":"2025-03-23T16:32:24.868Z","repository":{"id":34635420,"uuid":"181064220","full_name":"jschloer/use-multiselect","owner":"jschloer","description":"React hook for managing the selection state of a set of items. Does not require knowledge of the full set of items.","archived":false,"fork":false,"pushed_at":"2023-01-03T19:36:13.000Z","size":2063,"stargazers_count":8,"open_issues_count":48,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-04-27T11:45:08.486Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jschloer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-04-12T18:34:08.000Z","updated_at":"2023-07-14T17:14:44.000Z","dependencies_parsed_at":"2023-01-15T08:16:04.319Z","dependency_job_id":null,"html_url":"https://github.com/jschloer/use-multiselect","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jschloer%2Fuse-multiselect","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jschloer%2Fuse-multiselect/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jschloer%2Fuse-multiselect/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jschloer%2Fuse-multiselect/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jschloer","download_url":"https://codeload.github.com/jschloer/use-multiselect/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":221856461,"owners_count":16892443,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T07:00:38.898Z","updated_at":"2024-10-28T16:31:58.139Z","avatar_url":"https://github.com/jschloer.png","language":"JavaScript","funding_links":[],"categories":["Packages"],"sub_categories":[],"readme":"# use-multiselect\n\n\u003e React hook for managing the selection state of a set of items. Does not require the full list of items, so can therefore be used for lazy loaded lists.\n\n[![NPM](https://img.shields.io/npm/v/use-multiselect.svg)](https://www.npmjs.com/package/use-multiselect) [![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)\n\n## Install\n\n```bash\nnpm install --save use-multiselect\n```\n\n## Usage\n\nuseMultiSelect manages the set of items that are currently selected. We try to be a little clever by only keeping track of the items that are different from the default selection state. The way this works is we keep track of whether the default state of items is selected or not selected, and then keep a list of the exceptions to the default state. This means it can be used to manage a large list of objects that aren't necessarily fully known. You could then, for instance, use 'select all' on a lazy loaded list where not all items have been downloaded.\nYou also can choose to use useMultiselect as a standalone hook, or as a hook attached to a Context provider. Using the context provider allows you to better separate the multi select responsiblity among components.\nStandalone usage is shown below:\n\n```tsx\nimport * as React from \"react\";\n\nimport { useMultiSelect } from \"use-multiselect\";\n\nconst Example = () =\u003e {\n  const { isSelected, setSelected } = useMultiSelect();\n  return (\n    \u003cdiv\u003e\n      {items.map((item) =\u003e {\n        return (\n          \u003cdiv\u003e\n            \u003clabel key={item}\u003e\n              {item}\n              \u003cinput\n                type=\"checkbox\"\n                item={item}\n                checked={isSelected(item)}\n                onChange={(ev) =\u003e setSelected(item, ev.target.checked)}\n              /\u003e\n            \u003c/label\u003e\n          \u003c/div\u003e\n        );\n      })}\n    \u003c/div\u003e\n  );\n};\n```\n\nProvider Based\n\n```tsx\nimport * as React from \"react\";\n\nimport {\n  useMultiSelectWithProvider,\n  MultiSelectContextProvider,\n} from \"use-multiselect\";\nconst UpperComponent = () =\u003e {\n  \u003cMultiSelectContextProvider\u003e\n    \u003cdiv\u003e\n      Other stuff in here\n      \u003cExample /\u003e\n    \u003c/div\u003e\n  \u003c/MultiSelectContextProvider\u003e;\n};\nconst Example = () =\u003e {\n  const { isSelected, setSelected } = useMultiSelectWithProvider();\n  return (\n    \u003cdiv\u003e\n      {items.map((item) =\u003e {\n        return (\n          \u003cdiv\u003e\n            \u003clabel key={item}\u003e\n              {item}\n              \u003cinput\n                type=\"checkbox\"\n                item={item}\n                checked={isSelected(item)}\n                onChange={(ev) =\u003e setSelected(item, ev.target.checked)}\n              /\u003e\n            \u003c/label\u003e\n          \u003c/div\u003e\n        );\n      })}\n    \u003c/div\u003e\n  );\n};\n```\n\n## useMultiSelect (isMultiSelectActive: boolean, allSelected: boolean, exceptions: Array\u003cstring\u003e) =\u003e {...Returned functions}\n\nuseMultiSelect takes an initial state object defining which items are currently selected. allSelected defines whether the default state is selected or not, and exceptions is a list of keys that are set to the opposite of the default state. This is the same structure as returned by getSelectionState()\n\n## useMultiSelectWithProvider () =\u003e {...Returned functions}\n\nuseMultiSelectWithProvider has no parameters as it gets its values from the included Context Provider component. It returns the same functions as the useMultiSelect hook\n\n## MultiSelectContextProvider (isMultiSelectActive: boolean, allSelected: boolean, exceptions: Array\u003cstring\u003e)\n\nThis component provides the context used by useMultiSelectWithProvider. It should be placed as close to the consuming hooks as possible. It accepts initial values to be used by the consuming hooks.\n**note that these are just initialization values and they are not monitored. Changing them will not affect the current state of the multiSelect**\n\n## Returned functions/values\n\n### isMultiSelectActive: boolean\n\nA convenience state to manage whether or not mutliSelect is currently active.\n\n### function setMultiSelectActive:(value: boolean) =\u003e void\n\nSets the current value of isMultiSelectActive. This doesn't affect the selection state at all. i.e. you can turn multiselect on and off, but the selected status of all items will remain the same\n\n### function setSelected(key: string, value: boolean) =\u003e void\n\nTakes a key and value and sets the item to the given value.\n\n### function toggleSelected(key: string) =\u003e void\n\nTakes a key and toggles the current selected value of that key\n\n### function selectAll() =\u003e void\n\nMarks all keys as selected.\n\n### function deSelectAll() =\u003e void\n\nMarks all keys as not selected.\n\n### function isSelected(key: string) =\u003e boolean\n\nReturns true or false based on whether the given item iscurrently selected\n\n### function getAllSelectedKeys(keys: Array\u003cstring\u003e) =\u003e Array\u003cstring\u003e\n\nFilters the given array of keys, returning just the selected ones.\n\n### function getSelectedCount(totalCount: number) =\u003e number\n\nReturns the number of items currently selected. It requires the totalCount as a parameter so it can calculate the difference between the total number, and the selected amount, when for instance the select all is pressed and then a single item is deselected.\n\n### function getSelectionState() =\u003e {allSelected: boolean, exceptions: Array\u003cstring\u003e}\n\nReturns the internal selection state used by useMultiSelect. This can be used, for instance, to support multiSelect with lazy loaded items. The returned object has enough information to recreate teh selection set elsewhere for processing of commands.\n\n### stateHash: string\n\nThis is a hash value defined by the internal state of the selection set(note, that this does not include the isMultiSelectActive field). This hash value can be used as a quick way to determine if the state of selection has changed. This can be particularly valuable for hook dependencies.\n\n## License\n\nMIT © [jschloer](https://github.com/jschloer)\n\n---\n\nThis hook is created using [create-react-hook](https://github.com/hermanya/create-react-hook).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjschloer%2Fuse-multiselect","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjschloer%2Fuse-multiselect","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjschloer%2Fuse-multiselect/lists"}