# prompt-choices
> Create an array of multiple choice objects for use in prompts.
Latest version **5.0.0** (published 2018-05-28) · MIT license · 0 weekly downloads
## Install
```sh
npm install prompt-choices
pnpm add prompt-choices
yarn add prompt-choices
bun add prompt-choices
```
## Health
**Score 15/100 (F)** — status: abandoned.
Positive: no vulnerabilities.
Warnings: low downloads; no types; no esm support.
Negative: abandoned; low maintenance score.
## Facts
| | |
|---|---|
| Version | 5.0.0 |
| Published | 2018-05-28 |
| First published | 2016-08-29 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=4.0.0 |
| Dependencies | 16 |
| Unpacked size | 41.8 KB |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 18 |
| Author | Jon Schlinkert |
| Maintainers | jonschlinkert |
| Keywords | answer, answers, ask, checkbox, choice, choices, cli, command, enquirer, enquirerprompt, input, inquire, inquirer, interact, list, menu, password, prompt, prompts, question, readline, stdin, stdout, terminal, tty, ui |
## Links
- npm: https://www.npmjs.com/package/prompt-choices
- Repository: https://github.com/enquirer/prompt-choices
- Issues: https://github.com/enquirer/prompt-choices/issues
- npm.io page: https://npm.io/package/prompt-choices
## Dependencies (16)
- [koalas](https://npm.io/package/koalas.md) ^1.0.2
- [kind-of](https://npm.io/package/kind-of.md) ^6.0.2
- [arr-swap](https://npm.io/package/arr-swap.md) ^1.0.1
- [is-number](https://npm.io/package/is-number.md) ^6.0.0
- [log-utils](https://npm.io/package/log-utils.md) ^0.2.1
- [set-value](https://npm.io/package/set-value.md) ^3.0.0
- [clone-deep](https://npm.io/package/clone-deep.md) ^4.0.0
- [arr-flatten](https://npm.io/package/arr-flatten.md) ^1.1.0
- [strip-color](https://npm.io/package/strip-color.md) ^0.1.0
- [radio-symbol](https://npm.io/package/radio-symbol.md) ^2.0.0
- [toggle-array](https://npm.io/package/toggle-array.md) ^1.0.1
- [pointer-symbol](https://npm.io/package/pointer-symbol.md) ^1.0.0
- [define-property](https://npm.io/package/define-property.md) ^2.0.2
- [collection-visit](https://npm.io/package/collection-visit.md) ^1.0.0
- [choices-separator](https://npm.io/package/choices-separator.md) ^2.0.0
- [terminal-paginator](https://npm.io/package/terminal-paginator.md) ^2.0.2
## 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
- 5.0.0 (latest) — 2018-05-28
- 4.1.0 — 2018-05-28
- 4.0.6 — 2018-03-21
- 4.0.5 — 2017-08-29
- 4.0.4 — 2017-06-05
- 4.0.3 — 2017-06-03
- 4.0.2 — 2017-06-02
- 4.0.1 — 2017-06-02
- 4.0.0 — 2017-05-28
- 3.0.6 — 2017-05-24
- 3.0.5 — 2017-05-24
- 3.0.4 — 2017-05-23
- 3.0.3 — 2017-05-23
- 3.0.2 — 2017-05-21
- 3.0.1 — 2017-05-21
- … 15 more at https://npm.io/package/prompt-choices/versions
## README
# prompt-choices [](https://www.npmjs.com/package/prompt-choices) [](https://npmjs.org/package/prompt-choices) [](https://npmjs.org/package/prompt-choices) [](https://travis-ci.org/enquirer/prompt-choices)
> Create an array of multiple choice objects for use in prompts.
Please consider following this project's author, [Jon Schlinkert](https://github.com/jonschlinkert), and consider starring the project to show your :heart: and support.
## Install
Install with [npm](https://www.npmjs.com/):
```sh
$ npm install --save prompt-choices
```
## Usage
```js
var Choices = require('prompt-choices');
var choices = new Choices(['foo', 'bar', 'baz']);
```
## API
### [Choices](index.js#L21)
Create a new `Choices` collection.
**Params**
* `choices` **{Array}**: One or more `choice` strings or objects.
**Example**
```js
const choices = new Choices(['foo', 'bar', 'baz']);
const choices = new Choices([{name: 'foo'}, {name: 'bar'}, {name: 'baz'}]);
```
### [.render](index.js#L52)
Render choices.
**Params**
* `position` **{Number}**: Cursor position
* `options` **{Object}**
* `returns` **{String}**
### [.renderChoice](index.js#L90)
Render a specific choice. This can be overridden in prompts.
**Params**
* `choice` **{Object}**
* `position` **{Number}**
* `options` **{Object}**
* `returns` **{String}**: Returns the line to render.
**Example**
```js
choices.render = function(choice, position, options) {
// do custom logic
return '';
};
```
### [.choice](index.js#L105)
Create a new `Choice` object.
**Params**
* `val` **{String|Object}**
* `returns` **{Object}**: Returns a choice object.
**Example**
```js
choices.choice('blue');
```
### [.toChoice](index.js#L123)
Returns a normalized `choice` object.
**Params**
* `choice` **{Object|String}**
* `returns` **{Object}**
**Example**
```js
choices.toChoice('foo');
choices.toChoice({name: 'foo'});
```
### [.addChoice](index.js#L143)
Add a normalized `choice` object to the `choices` array.
**Params**
* `choice` **{string|Object}**: One or more choices to add.
**Example**
```js
choices.addChoice(['foo', 'bar', 'baz']);
```
### [.addChoices](index.js#L173)
Add an array of normalized `choice` objects to the `choices` array. This method is called in the constructor, but it can also be used to add choices after instantiation.
**Params**
* `choices` **{Array|Object}**: One or more choices to add.
**Example**
```js
choices.addChoices(['foo', 'bar', 'baz']);
```
### [.toGroups](index.js#L206)
Create choice "groups" from the given choices object. .
**Params**
* `choices` **{Object}**: (required) The value of each object must be an array of choices (strings or objects).
* `returns` **{Array}**: Returns an array of normalized choice objects.
**Example**
```js
choices.toGroups({
foo: ['a', 'b', 'c'],
bar: ['d', 'e', 'f']
});
```
### [.separator](index.js#L282)
Create a new `Separator` object. See [choices-separator](https://github.com/enquirer/choices-separator) for more details.
**Params**
* `separator` **{String}**: Optionally pass a string to use as the separator.
* `returns` **{Object}**: Returns a separator object.
**Example**
```js
choices.separator();
```
### [.hasChoice](index.js#L298)
Returns true if a choice exists.
**Params**
* `val` **{Number}**: The index or key of the choice to check for.
* `returns` **{Boolean}**
**Example**
```js
choices.hasChoice(1);
choices.hasChoice('foo');
```
### [.getChoice](index.js#L314)
Get a non-separator choice from the collection.
**Params**
* `idx` **{Number}**: The selected choice index
* `returns` **{Object|undefined}**: Return the matched choice object or undefined
**Example**
```js
choices.getChoice(1);
choices.getChoice('foo');
```
### [.getIndex](index.js#L341)
Get the index of a non-separator choice from the collection.
**Params**
* `key` **{String}**: The key of the choice to get
* `returns` **{Number}**: Index of the choice or `-1`;
**Example**
```js
const choices = new Choices(['foo', 'bar', 'baz']);
console.log(choices.getIndex('foo')); //=> 0
console.log(choices.getIndex('baz')); //=> 2
console.log(choices.getIndex('bar')); //=> 1
console.log(choices.getIndex('qux')); //=> -1
```
### [.get](index.js#L365)
Get the choice at the specified index.
**Params**
* `key` **{Number|String}**: The name or index of the object to get
* `returns` **{Object}**: Returns the specified choice
**Example**
```js
const choice = choices.get(1);
//=> {name: 'foo'}
const choice = choices.get(1, 'name');
//=> 'foo'
```
### [.clear](index.js#L389)
Clear all choices from the instance. This is useful when you need to update the indices of choices without re-instantiating.
**Example**
```js
choices.clear();
```
### [.key](index.js#L403)
Return the `.key` property from the choice at the given index.
**Params**
* `key` **{String}**: Property name to use for plucking objects.
* `returns` **{Array}**: Plucked objects
### [.check](index.js#L417)
Check the choice at the given `idx`.
**Params**
* `val` **{Number|Array}**: The key(s) or index(s) of the choice(s) to check.
**Example**
```js
choices.check(1);
```
### [.uncheck](index.js#L442)
Disable the choice at the given `idx`.
**Params**
* `idx` **{Number}**: The index of the choice to enable.
**Example**
```js
choices.uncheck(1);
```
### [.isChecked](index.js#L473)
Returns true if a choice is checked.
**Params**
* `name` **{String|Number}**: Name or index of the choice.
* `returns` **{Boolean}**
**Example**
```js
const choices = new Choices(['foo', 'bar', 'baz']);
console.log(choices.isChecked('foo'));
//=> false
choices.check('foo');
console.log(choices.isChecked('foo'));
//=> true
```
### [.toggle](index.js#L501)
Toggle the choice at the given `idx`.
**Params**
* `idx` **{Number}**: The index of the choice to toggle.
**Example**
```js
choices.toggle(1);
// radio mode
choices.toggle(1, true);
```
### [.swap](index.js#L609)
Swap two choices in the choices array.
**Params**
* `a` **{String|Number}**
* `b` **{String|Number}**
* `returns` **{Object}**: Returns the `Choices` instance
### [.where](index.js#L625)
Return choice values for choices that return truthy based
on the given `val`.
**Params**
* `val` **{Array|Object|Function|String|RegExp}**
* `returns` **{Array}**: Matching choices or empty array
### [.isItem](index.js#L673)
Returns true if the given `choice` is a valid choice item, and
not a "group" or "radio" choice.
**Params**
* `key` **{String}**: Property name to use for plucking objects.
* `returns` **{Array}**: Plucked objects
### [.isValidIndex](index.js#L688)
Returns true if the given `index` is a valid choice index.
**Params**
* `key` **{String}**: Property name to use for plucking objects.
* `returns` **{Array}**: Plucked objects
### [.pluck](index.js#L699)
Pluck an object with the specified key from the choices collection.
**Params**
* `key` **{String}**: Property name to use for plucking objects.
* `returns` **{Array}**: Plucked objects
### [.default](index.js#L735)
Getter for getting the default choice.
### [.checked](index.js#L762)
Getter for getting the checked choices from the collection.
### [.length](index.js#L804)
Getter for getting the length of the collection.
### [.Separator](index.js#L824)
Create a new `Separator` object. See [choices-separator](https://github.com/enquirer/choices-separator) for more details.
**Params**
* `separator` **{String}**: Optionally pass a string to use as the separator.
* `returns` **{Object}**: Returns a separator object.
**Example**
```js
new Choices.Separator();
```
### [.isChoices](index.js#L840)
Create a new `Separator` object. See [choices-separator](https://github.com/enquirer/choices-separator) for more details.
**Params**
* `choices` **{String}**: The value to test.
* `returns` **{Boolean}**: Returns true if the given value is an instance of `Choices`.
**Example**
```js
const Choices = require('prompt-choices');
const choices = new Choices(['foo']);
console.log(Choices.isChoices(choices)); //=> true
console.log(Choices.isChoices({})); //=> false
```
### [.isChoice](index.js#L859)
Create a new `Separator` object. See [choices-separator](https://github.com/enquirer/choices-separator) for more details.
**Params**
* `choice` **{String}**: The value to test.
* `returns` **{Boolean}**: Returns true if the given value is an instance of `Choice`.
**Example**
```js
const Choices = require('prompt-choices');
const choices = new Choices(['foo']);
const foo = choices.getChoice('foo');
console.log(Choices.isChoice(foo)); //=> true
console.log(Choices.isChoice({})); //=> false
```
## Release history
### v3.0.2
**Added**
* adds array support to `.isChecked`
**Fixed**
* ensures that choice groups are checked/unchecked based on group items
### v3.0.0
**Added**
* adds support for choice "groups"! This allows you to define an object of choice arrays, where each key in the object creates a choice group.
### v2.0.0
**Changed**
* renamed `Move` class to `Actions`
* renamed `choices.move` property to `choices.actions`
**Removed**
* removed `.enable` and `.disable` prototype methods from both `Choice` and `Choices`. These methods were ambiguous as they blurred the distinction between "enabling" a choice (meaning that it's "checked") versus enabling a property on a choice. If this is confusing, that's why they were removed.
**Added**
* adds `Actions` class (previously named `Move`) for managing actions on choices
* adds `.addChoice` prototype method, for adding a single choice after instantiation
* adds `.action` prototype method to `Choices`, which calls a method on the `Actions` class
* adds `.check` and `.uncheck` prototype methods (previously ambiguously named `.enable` and `.disable`)
## Attribution
Some of the code in this library was initially based on the `Choices` class in Inquirer.
## About
Contributing
Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).
Running Tests
Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:
```sh
$ npm install && npm test
```
Building docs
_(This project's readme.md is generated by [verb](https://github.com/verbose/verb-generate-readme), please don't edit the readme directly. Any changes to the readme must be made in the [.verb.md](.verb.md) readme template.)_
To generate the readme, run the following command:
```sh
$ npm install -g verbose/verb#dev verb-generate-readme && verb
```
### Related projects
You might also be interested in these projects:
* [enquirer](https://www.npmjs.com/package/enquirer): Intuitive, plugin-based prompt system for node.js. | [homepage](http://enquirer.io "Intuitive, plugin-based prompt system for node.js.")
* [prompt-base](https://www.npmjs.com/package/prompt-base): Base prompt module used for creating custom prompts. | [homepage](https://github.com/enquirer/prompt-base "Base prompt module used for creating custom prompts.")
* [prompt-checkbox](https://www.npmjs.com/package/prompt-checkbox): Multiple-choice/checkbox prompt. Can be used standalone or with a prompt system like [Enquirer]. | [homepage](https://github.com/enquirer/prompt-checkbox "Multiple-choice/checkbox prompt. Can be used standalone or with a prompt system like [Enquirer].")
* [prompt-question](https://www.npmjs.com/package/prompt-question): Question object, used by Enquirer and prompt plugins. | [homepage](https://github.com/enquirer/prompt-question "Question object, used by Enquirer and prompt plugins.")
* [prompt-radio](https://www.npmjs.com/package/prompt-radio): Radio prompt. Can be used as a standalone prompt, or as a plugin for [Enquirer]. | [homepage](https://github.com/enquirer/prompt-radio "Radio prompt. Can be used as a standalone prompt, or as a plugin for [Enquirer].")
### Author
**Jon Schlinkert**
* [LinkedIn Profile](https://linkedin.com/in/jonschlinkert)
* [GitHub Profile](https://github.com/jonschlinkert)
* [Twitter Profile](https://twitter.com/jonschlinkert)
### License
Copyright © 2018, [Jon Schlinkert](https://github.com/jonschlinkert).
Released under the [MIT License](LICENSE).
***
_This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.6.0, on May 28, 2018._
---
_Source: https://npm.io/package/prompt-choices · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._