# align-text [](http://badge.fury.io/js/align-text) [](https://travis-ci.org/jonschlinkert/align-text) > Align the text in a string. **Examples** Align text values in an array: ```js align([1, 2, 3, 100]); //=> [' 1', ' 2', ' 3', '100'] ``` Or [do stuff like this](./example.js): [](./example.js) Visit [the example](./example.js) to see how this works. ## Install Install with [npm](https://www.npmjs.com/) ```sh $ npm i align-text --save ``` ## Usage ```js var align = require('align-text'); align(text, callback_function_or_integer); ``` **Params** * `text` can be a **string or array**. If a string is passed, a string will be returned. If an array is passed, an array will be returned. * `callback|integer`: if an integer, the text will be indented by that amount. If a function, it must return an integer representing the amount of leading indentation to use as `align` loops over each line. **Example** ```js align(text, 4); ``` Would align: ``` abc abc abc ``` To: ``` abc abc abc ``` ## callback ### params The callback is used to determine the indentation of each line and gets the following params: * `len` the length of the "current" line * `longest` the length of the longest line * `line` the current line (string) being aligned * `lines` the array of all lines ### return The callback may return: * an integer that represents the number of spaces to use for padding, * or an object with the following properties: - `indent`: **{Number}** the amount of indentation to use. Default is `0` when an object is returned. - `character`: **{String}** the character to use for indentation. Default is `''` (empty string) when an object is returned. - `prefix`: **{String}** leading characters to use at the beginning of each line. `''` (empty string) when an object is returned. **Integer example:** ```js // calculate half the difference between the length // of the current line and the longest line function centerAlign(len, longest, line, lines) { return Math.floor((longest - len) / 2); } ``` **Object example:** ```js function centerAlign(len, longest, line, lines) { return { character: '\t', indent: Math.floor((longest - len) / 2), prefix: '~ ', } } ``` ## Usage examples ### Center align Using the `centerAlign` function from above: ```js align(text, centerAlign); ``` Would align this text: ```js Lorem ipsum dolor sit amet consectetur adipiscin elit, sed do eiusmod tempor incididun ut labore et dolor magna aliqua. Ut enim ad mini veniam, quis ``` Resulting in this: ``` Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis ``` **Customize** If you wanted to add more padding on the left, just pass the number in the callback. For example, to add 4 spaces before every line: ```js function centerAlign(len, longest, line, lines) { return 4 + Math.floor((longest - len) / 2); } ``` Would result in: ``` Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis ``` ### Bullets ```js align(text, function (len, max, line, lines) { return {prefix: ' - '}; }); ``` Would return: ``` - Lorem ipsum dolor sit amet, - consectetur adipiscing - elit, sed do eiusmod tempor incididunt - ut labore et dolore - magna aliqua. Ut enim ad minim - veniam, quis ``` ### Different indent character ```js align(text, function (len, max, line, lines) { return { indent: Math.floor((max - len) / 2), character: '~', }; }); ``` Would return ``` ~~~~~Lorem ipsum dolor sit amet, ~~~~~~~~consectetur adipiscing elit, sed do eiusmod tempor incididunt ~~~~~~~~~ut labore et dolore ~~~~magna aliqua. Ut enim ad minim ~~~~~~~~~~~~~veniam, quis ``` ## Related projects * [center-align](https://github.com/jonschlinkert/center-align): Center-align the text in a string. * [justify](https://github.com/bahamas10/node-justify): Left or right (or both) justify text using a custom width and character * [longest](https://github.com/jonschlinkert/longest): Get the longest item in an array. * [right-align](https://github.com/jonschlinkert/right-align): Right-align the text in a string. * [repeat-string](https://github.com/jonschlinkert/repeat-string): Repeat the given string n times. Fastest implementation for repeating a string. * [word-wrap](https://github.com/jonschlinkert/word-wrap): Wrap words to a specified length. ## 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/align-text/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-cli](https://github.com/assemble/verb-cli) on June 09, 2015._