# atom-select-list
> A general-purpose select list for use in Atom packages
Latest version **0.8.1** (published 2021-05-21) · MIT license · 0 weekly downloads
## Install
```sh
npm install atom-select-list
pnpm add atom-select-list
yarn add atom-select-list
bun add atom-select-list
```
## Health
**Score 15/100 (F)** — status: abandoned.
Positive: no vulnerabilities.
Warnings: low downloads; no types; no esm support; pre 1.0.
Negative: abandoned; low maintenance score.
## Facts
| | |
|---|---|
| Version | 0.8.1 |
| Published | 2021-05-21 |
| First published | 2016-11-22 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 102.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 33 |
| Maintainers | nathansobo, maxbrunsfeld, as-cii, daviwil, iolsen, ben3eee, atom-team |
## Links
- npm: https://www.npmjs.com/package/atom-select-list
- Repository: https://github.com/atom/atom-select-list
- Homepage: https://github.com/atom/atom-select-list#readme
- Issues: https://github.com/atom/atom-select-list/issues
- npm.io page: https://npm.io/package/atom-select-list
## Dependencies (2)
- [etch](https://npm.io/package/etch.md) ^0.14.0
- [fuzzaldrin](https://npm.io/package/fuzzaldrin.md) ^2.1.0
## Recent versions
- 0.8.1 (latest) — 2021-05-21
- 0.8.0 — 2021-01-12
- 0.7.2 — 2018-08-20
- 0.7.1 — 2018-02-27
- 0.7.0 — 2017-12-01
- 0.6.0 — 2017-11-22
- 0.5.0 — 2017-11-14
- 0.4.0 — 2017-11-14
- 0.3.2 — 2017-10-02
- 0.3.1 — 2017-10-02
- 0.3.0 — 2017-09-05
- 0.2.0 — 2017-03-26
- 0.1.0 — 2017-03-22
- 0.0.16 — 2017-02-28
- 0.0.15 — 2017-02-27
- … 14 more at https://npm.io/package/atom-select-list/versions
## README
# atom-select-list
This module is an [etch component](https://github.com/atom/etch) that can be used in Atom packages to show a select list with fuzzy filtering, keyboard/mouse navigation and other cool features.
## Installation
```bash
npm install --save atom-select-list
```
## Usage
After installing the module, you can simply require it and use it as a standalone component:
```js
const SelectList = require('atom-select-list')
const usersSelectList = new SelectList({
items: ['Alice', 'Bob', 'Carol']
})
document.body.appendChild(usersSelectList.element)
```
Or within another etch component:
```jsx
render () {
return (
)
}
```
## API
When creating a new instance of a select list, or when calling `update` on an existing one, you can supply a JavaScript object that can contain any of the following properties:
* `items: [Object]`: an array containing the objects you want to show in the select list.
* `elementForItem: (item: Object, options: Object) -> HTMLElement`: a function that is called whenever an item needs to be displayed.
* `options: Object`:
* `selected: Boolean`: indicating whether item is selected or not.
* `index: Number`: item's index.
* `visible: Boolean`: indicating whether item is visible in viewport or not. Unless `initiallyVisibleItemCount` was given, this value is always `true`.
* (Optional) `maxResults: Number`: the number of maximum items that are shown.
* (Optional) `filter: (items: [Object], query: String) -> [Object]`: a function that allows to decide which items to show whenever the query changes. By default, it uses [fuzzaldrin](https://github.com/atom/fuzzaldrin) to filter results.
* (Optional) `filterKeyForItem: (item: Object) -> String`: when `filter` is not provided, this function will be called to retrieve a string property on each item and that will be used to filter them.
* (Optional) `filterQuery: (query: String) -> String`: a function that allows to apply a transformation to the user query and whose return value will be used to filter items.
* (Optional) `query: String`: a string that will replace the contents of the query editor.
* (Optional) `selectQuery: Boolean`: a boolean indicating whether the query text should be selected or not.
* (Optional) `order: (item1: Object, item2: Object) -> Number`: a function that allows to change the order in which items are shown.
* (Optional) `emptyMessage: String`: a string shown when the list is empty.
* (Optional) `errorMessage: String`: a string that needs to be set when you want to notify the user that an error occurred.
* (Optional) `infoMessage: String`: a string that needs to be set when you want to provide some information to the user.
* (Optional) `loadingMessage: String`: a string that needs to be set when you are loading items in the background.
* (Optional) `loadingBadge: String/Number`: a string or number that needs to be set when the progress status changes (e.g. a percentage showing how many items have been loaded so far).
* (Optional) `itemsClassList: [String]`: an array of strings that will be added as class names to the items element.
* (Optional) `initialSelectionIndex: Number`: the index of the item to initially select and automatically select after query changes; defaults to `0`.
* (Optional) `didChangeQuery: (query: String) -> Void`: a function that is called when the query changes.
* (Optional) `didChangeSelection: (item: Object) -> Void`: a function that is called when the selected item changes.
* (Optional) `didConfirmSelection: (item: Object) -> Void`: a function that is called when the user clicks or presses Enter on an item.
* (Optional) `didConfirmEmptySelection: () -> Void`: a function that is called when the user presses Enter but the list is empty.
* (Optional) `didCancelSelection: () -> Void`: a function that is called when the user presses Esc or the list loses focus.
* (Optional) `initiallyVisibleItemCount: Number`: When this options was provided, `SelectList` observe visibility of items in viewport, visibility state is passed as `visible` option to `elementForItem`. This is mainly used to skip heavy computation for invisible items.
---
_Source: https://npm.io/package/atom-select-list · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._