atom-select-list

atom-select-list

This module is an etch component that can be used in Atom packages to show a select list with fuzzy filtering, keyboard/mouse navigation and other cool features.

Installation

npm install --save atom-select-list

Usage

After installing the module, you can simply require it and use it as a standalone component:

const SelectList = require('atom-select-list')

const usersSelectList = new SelectList({
  items: ['Alice', 'Bob', 'Carol']
})
document.body.appendChild(usersSelectList.element)

Or within another etch component:

render () {
  return (
    <SelectList items={this.items} />
  )
}

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) -> HTMLElement: a function that is called whenever an item needs to be displayed.
• (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 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) 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) 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.