align-text

Align the text in a string.

Examples

Align text values in an array:

align([1, 2, 3, 100]);
//=> ['  1', '  2', '  3', '100']

Or do stuff like this:

Visit the example to see how this works.

Install

Install with npm

$ npm i align-text --save

Usage

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

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:

// 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:

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:

align(text, centerAlign);

Would align this text:

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:

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

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

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

center-align: Center-align the text in a string.
justify: Left or right (or both) justify text using a custom width and character
longest: Get the longest item in an array.
right-align: Right-align the text in a string.
repeat-string: Repeat the given string n times. Fastest implementation for repeating a string.
word-wrap: Wrap words to a specified length.

Running tests

Install dev dependencies:

$ npm i -d && npm test

Contributing

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue

Author

Jon Schlinkert

License

This file was generated by verb-cli on June 09, 2015.