cli-list-select

Simple command line interactive list

Install

npm i cli-list-select

Description

Package exports single function

const list = require('cli-list-select');

Function is async and has 2 arguments.

Function arguments

Name	Type	Description
items	any[]	items to be displayed
options?	Option	options

Returns Result

Options

Field	Type	Default	Description
printItem	(item: any, index: number, isFocused: bool, isChecked: bool) => string	String	function that provides string representation for an item
index	number	0	initial focus position
singleCheck	bool	false	tells if only one item can be checked
checks	number[] | number	[] | NaN	initially checked items
handlers	Handlers	{}	custom key handlers

Handlers

It is a map.

Field	Type	Description
key	string	key name
value	(arg: HandlerArg) => void	key handler

Default handlers are

Key	Handler
up	move focus to previous item
down	move focus to next item
space	toggle check of the focused item
return	close the list

HandlerArg

Field	Type	Description
index	number	current focus
setIndex	(index: number) => void	function that sets current focus
toggleCheck	(index: number) => void	function that toggles check state of an item
end	(note: any) => void	function that closes the list

Result

Field	Type	Description
index	number	focus
checks	number[] | number	checked items
note	any	note returned in the end function

Call

Just print a list

await list(['A', 'B', 'C']);

-[ ] A
 [ ] B
 [ ] C

Set initial focus

await list(['A', 'B', 'C'], { index: 1 });

 [ ] A
-[ ] B
 [ ] C

Check an item

 [*] A
-[*] B
 [ ] C

Single check mode

await list(['A', 'B', 'C'], { singleCheck: true });

 [ ] A
-[*] B
 [ ] C

Initial checks

await list(['A', 'B', 'C'], { checks: [0, 2] });

-[*] A
 [ ] B
 [*] C

Custom print

await list([{ data: 'A' }, { data: 'B' }, { data: 'C' }], {
    printItem: item => `<${item.data}>`
});

-[ ] <A>
 [ ] <B>
 [ ] <C>

Custom handlers

await list(['A', 'B', 'C'], {
    handlers: {
        'q': ({ end }) => end('Q'),
    },
});

Examples

• simple
• print
• single-mode
• handlers