# list-item [![NPM version](https://img.shields.io/npm/v/list-item.svg)](https://www.npmjs.com/package/list-item) [![Build Status](https://img.shields.io/travis/jonschlinkert/list-item.svg)](https://travis-ci.org/jonschlinkert/list-item)

> Generate a single formatted list item, allowing you to easily generate lists with proper indentation, bullets, numbers or other leading characters.

- [Install](#install)
- [Usage](#usage)
- [Examples](#examples)
- [API](#api)
- [Related projects](#related-projects)
- [Running tests](#running-tests)
- [Contributing](#contributing)
- [Author](#author)
- [License](#license)

_(TOC generated by [verb](https://github.com/verbose/verb))_

## Install

Install with [npm](https://www.npmjs.com/)

```sh
$ npm i list-item --save
```

## Usage

```js
var listitem = require('list-item');
```

## Examples

**Basic list**

Generate a list using default bullets and indentation:

```js
var listitem = require('list-item');
var li = listitem();
var res = '';

['a', 'b', 'c', 'd', 'e'].forEach(function (ele, i) {
  res += li(i, ele) + '\n';
});
```

Results in:

```
- a
  * b
    + c
      - d
        * e
```

**Roman numerals**

Generate roman numerals in increments of 10.

```js
var listitem = require('list-item');
var romanize = require('romanize');

// specify `chars` to be passed to expand-range (lib), 
// and use the callback to modify generated numerals
var li = listitem({chars: '1..100..10'}, function (ch) {
  return romanize(ch) + '.';
});

// generate a formatted list!
['a', 'b', 'c', 'd', 'e'].forEach(function (ele, i) {
  res += li(i, ele) + '\n';
});
```

Results in:

```
I. a
  XI. b
    XXI. c
      XXXI. d
        XLI. e
```

## API

### [listitem](index.js#L47)

Returns a function to generate a plain-text/markdown list-item, allowing options to be cached for subsequent calls.

**Params**

* `options` **{Object}**: pass options to customize list item characters, indentation, etc.
* `options.nobullet` **{Boolean}**: Pass true if you only want the list iten and identation, but no bullets.
* `options.indent` **{String}**: The amount of leading indentation to use. default is ``.
* `options.chars` **{String|Array}**: If a string is passed, [expand-range](https://github.com/jonschlinkert/expand-range) will be used to generate an array of bullets (visit [expand-range](https://github.com/jonschlinkert/expand-range) to see all options.) Or directly pass an array of bullets, numbers, letters or other characters to use for each list item. Default `['-', '*', '+']`
* `fn` **{Function}**: pass a function [expand-range](https://github.com/jonschlinkert/expand-range) to modify the bullet for an item as it's generated. See the [examples](#examples).
* `returns` **{String}**: returns a formatted list item

**Example**

```js
var li = listitem(options);

li(0, 'Level 0 list item');
//=> '- Level 0 list item'

li(1, 'Level 1 list item');
//=> '  * Level 1 list item'

li(2, 'Level 2 list item');
//=> '    + Level 2 list item'
```

## Related projects

* [deromanize](https://www.npmjs.com/package/deromanize): Convert roman numerals to arabic numbers (useful for books, outlines, documentation, slide decks, etc) | [homepage](https://github.com/jonschlinkert/deromanize)
* [expand-range](https://www.npmjs.com/package/expand-range): Fast, bash-like range expansion. Expand a range of numbers or letters, uppercase or lowercase. See… [more](https://www.npmjs.com/package/expand-range) | [homepage](https://github.com/jonschlinkert/expand-range)
* [fill-range](https://www.npmjs.com/package/fill-range): Fill in a range of numbers or letters, optionally passing an increment or multiplier to… [more](https://www.npmjs.com/package/fill-range) | [homepage](https://github.com/jonschlinkert/fill-range)
* [randomatic](https://www.npmjs.com/package/randomatic): Generate randomized strings of a specified length, fast. Only the length is necessary, but you… [more](https://www.npmjs.com/package/randomatic) | [homepage](https://github.com/jonschlinkert/randomatic)
* [romanize](https://www.npmjs.com/package/romanize): Convert numbers to roman numerals (useful for books, outlines, documentation, slide decks, etc) | [homepage](https://github.com/jonschlinkert/romanize)
* [to-regex-range](https://www.npmjs.com/package/to-regex-range): Returns a regex-compatible range from two numbers, min and max. Useful for creating regular expressions… [more](https://www.npmjs.com/package/to-regex-range) | [homepage](https://github.com/jonschlinkert/to-regex-range)

## Running tests

Install dev dependencies:

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

## Contributing

Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](https://github.com/jonschlinkert/list-item/issues/new).

## Author

**Jon Schlinkert**

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

## License

Copyright © 2015 [Jon Schlinkert](https://github.com/jonschlinkert)
Released under the MIT license.

***

_This file was generated by [verb](https://github.com/verbose/verb) on December 20, 2015._