# cli-list-select

> Simple command line interactive list

Latest version **0.0.7** (published 2022-05-09) · MIT license · 0 weekly downloads

## Install

```sh
npm install cli-list-select
pnpm add cli-list-select
yarn add cli-list-select
bun add cli-list-select
```

## 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.0.7 |
| Published | 2022-05-09 |
| First published | 2019-03-02 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=6.0 |
| Dependencies | 0 |
| Unpacked size | 8.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | Dmitry Bogomolov |
| Maintainers | dmitry_bogomolov |
| Keywords | list, console, cli, select, prompt, menu |

## Links

- npm: https://www.npmjs.com/package/cli-list-select
- Repository: https://github.com/DmitryBogomolov/cli-list-select
- Homepage: https://github.com/DmitryBogomolov/cli-list-select#readme
- Issues: https://github.com/DmitryBogomolov/cli-list-select/issues
- npm.io page: https://npm.io/package/cli-list-select

## Alternatives

- [@salesforce/cli](https://npm.io/package/@salesforce/cli.md) — 389.7K weekly downloads
- [@mintlify/cli](https://npm.io/package/@mintlify/cli.md) — 208.9K weekly downloads
- [@grafana/e2e-selectors](https://npm.io/package/@grafana/e2e-selectors.md) — 128.7K weekly downloads
- [mintlify](https://npm.io/package/mintlify.md) — 112.0K weekly downloads
- [@intlayer/cli](https://npm.io/package/@intlayer/cli.md) — 22.8K weekly downloads

## Recent versions

- 0.0.7 (latest) — 2022-05-09
- 0.0.6 — 2020-04-11
- 0.0.5 — 2019-11-13
- 0.0.4 — 2019-05-05
- 0.0.3 — 2019-03-03
- 0.0.2 — 2019-03-02
- 0.0.1 — 2019-03-02

## README

[![CI](https://github.com/DmitryBogomolov/cli-list-select/actions/workflows/ci.yml/badge.svg)](https://github.com/DmitryBogomolov/cli-list-select/actions/workflows/ci.yml)

# cli-list-select

Simple command line interactive list

## Install

```bash
npm i cli-list-select
```

## Description

Package exports single function

```js
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) | options

Returns [Result](#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](#Handlers) | {} | custom key handlers

### Handlers

It is a map.

Field | Type | Description
-|-|-
key | string | key name
value | (arg: [HandlerArg](#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

```js
await list(['A', 'B', 'C']);
```
```bash
-[ ] A
 [ ] B
 [ ] C
```

### Set initial focus

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

### Check an item

```bash
 [*] A
-[*] B
 [ ] C
```

### Single check mode

```js
await list(['A', 'B', 'C'], { singleCheck: true });
```
```bash
 [ ] A
-[*] B
 [ ] C
```

### Initial checks

```js
await list(['A', 'B', 'C'], { checks: [0, 2] });
```
```bash
-[*] A
 [ ] B
 [*] C
```

### Custom print

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

### Custom handlers

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

## Examples

- [simple](./examples/simple.js)
- [print](./examples/print.js)
- [single-mode](./examples/single-mode.js)
- [handlers](./examples/handlers.js)

---
_Source: https://npm.io/package/cli-list-select · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._