# prompt-choices [![NPM version](https://img.shields.io/npm/v/prompt-choices.svg?style=flat)](https://www.npmjs.com/package/prompt-choices) [![NPM downloads](https://img.shields.io/npm/dm/prompt-choices.svg?style=flat)](https://npmjs.org/package/prompt-choices) [![Build Status](https://img.shields.io/travis/enquirer/prompt-choices.svg?style=flat)](https://travis-ci.org/enquirer/prompt-choices)

> Create an array of multiple choice objects for use in prompts.

## 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#L19)

Create a new `Choices` collection.

**Params**

* `choices` **{Array}**: One or more `choice` strings or objects.

**Example**

```js
var choices = new Choices(['foo', 'bar', 'baz']);
var choices = new Choices([{name: 'foo'}, {name: 'bar'}, {name: 'baz'}]);
```

### [.addChoices](index.js#L44)

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(['a', 'b', 'c']);
```

### [.choice](index.js#L77)

Create a new `Choice` object.

**Params**

* `choice` **{String|Object}**
* `returns` **{Object}**: Returns a choice object.

**Example**

```js
choices.choice('blue');
```

### [.separator](index.js#L92)

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();
```

### [.getChoice](index.js#L107)

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);
```

### [.getIndex](index.js#L127)

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
choices.getChoice('foo');
```

### [.get](index.js#L148)

Get the choice or separator object at the specified index.

**Params**

* `idx` **{Number}**: The index of the object to get
* `returns` **{Object}**: Returns the specified choice

**Example**

```js
choices.getChoice(1);
```

### [.enable](index.js#L165)

Enable the choice at the given `idx`.

**Params**

* `idx` **{Number}**: The index of the choice to enable.

**Example**

```js
choices.enable(1);
```

### [.disable](index.js#L180)

Disable the choice at the given `idx`.

**Params**

* `idx` **{Number}**: The index of the choice to enable.

**Example**

```js
choices.disable(1);
```

### [.toggleChoices](index.js#L195)

Enable the choice at the given `index`, and disable all other choices.

**Params**

* `idx` **{Number}**: The index of the choice to toggle.

**Example**

```js
choices.toggleChoices(1);
```

### [.toggleChoice](index.js#L210)

Toggle the choice at the given `idx`.

**Params**

* `idx` **{Number}**: The index of the choice to toggle.

**Example**

```js
choices.toggleChoice(1);
```

### [.where](index.js#L224)

Return choices that return truthy based on the given `val`.

**Params**

* `val` **{Object|Function|String}**
* `returns` **{Array}**: Matching choices or empty array

### [.pluck](index.js#L259)

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

### [.length](index.js#L302)

Getter for getting the length of the collection.

### [.realChoices](index.js#L317)

Getter for getting all non-separator choices from the collection.

### [.realLength](index.js#L340)

Getter for getting the length of the collection excluding non-separator choices.

### [.Separator](index.js#L360)

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();
```

## Attribution

Code is partially 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).

### Building docs

_(This document was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme) (a [verb](https://github.com/verbose/verb) generator), please don't edit the readme directly. Any changes to the readme must be made in [.verb.md](.verb.md).)_

To generate the readme and API documentation with [verb](https://github.com/verbose/verb):

```sh
$ npm install -g verb verb-generate-readme && verb
```

### Running tests

Install dev dependencies:

```sh
$ npm install -d && npm test
```

### Author

**Jon Schlinkert**

* [github/jonschlinkert](https://github.com/jonschlinkert)
* [twitter/jonschlinkert](http://twitter.com/jonschlinkert)

### License

Copyright © 2016, [Jon Schlinkert](https://github.com/jonschlinkert).
Released under the [MIT license](https://github.com/enquirer/prompt-choices/blob/master/LICENSE).

***

_This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.1.30, on August 30, 2016._