string-word-wrap

Wrap a string to a maximum line length. Unicode-aware, with hyphen and soft hyphen breaking, and first-line or hanging indentation.

Installation

npm install string-word-wrap

Usage

import wordWrap from "string-word-wrap";

wordWrap("The quick brown fox jumps over the lazy dog", 20);
// The quick brown fox
// jumps over the lazy
// dog

wordWrap("--color  Enable colored output in the terminal", 26, {
  indent: 9,
  indentFirst: 0,
});
// --color  Enable colored
//          output in the
//          terminal

wordWrap("Quoted text to wrap", 10, { indent: "> " });
// > Quoted
// > text to
// > wrap

wordWrap("supercalifragilistic", 10, { breakLongWords: true });
// supercalif
// ragilistic

wordWrap("a well-known hy\u00ADphen\u00ADation", 11);
// a well-
// known hy-
// phenation

Lines break at whitespace, after hyphens between letters, and at soft hyphens (U+00AD), which render as - when used and are removed otherwise. Use a non-breaking hyphen (U+2011) or no-break space (U+00A0) to prevent a break.

Line length is measured in grapheme clusters (user-perceived characters): combining marks and emoji sequences count as one character and are never split. Display width (e.g. double-width CJK or emoji in terminals) is not accounted for.

CSS equivalents

| Option | CSS | | ----------------------- | --------------------------------------------------------- | | length | width (in ch) | | indent | padding-left (in ch) | | indentFirst | text-indent (in ch, relative to indent) | | breakLongWords: false | overflow-wrap: normal | | breakLongWords: true | overflow-wrap: break-word | | hyphens: "manual" | hyphens: manual | | hyphens: "none" | hyphens: none | | trim: false | white-space: pre-wrap (whitespace at breaks is dropped) | | trim: true | white-space: pre-wrap + leading whitespace removed |

API

Functions

Typedefs

wordWrap(string, [length], [options]) ⇒ string

Wrap a string to a maximum number of characters per line, optionally with indentation.

Kind: global function

| Param | Type | Default | | --------- | ------------------------------------------------ | --------------- | | string | string | | | [length] | number | 10 | | [options] | WordWrapOptions | {} |

WordWrapOptions : object

Kind: global typedef Properties

| Name | Type | Default | Description | | ---------------- | ---------------------------------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------- | | [indent] | number | string | 0 | Number of spaces (or string) to prefix lines after the first one with. | | [indentFirst] | number | string | indent | Number of spaces (or string) to prefix the first line with. | | [newlineChar] | string | ""\n"" | The characters to insert at the end of each line. | | [global] | boolean | true | Wrap the whole string or just the first line. | | [breakLongWords] | boolean | false | Break words longer than the available line width. | | [hyphens] | "none" | "manual" | "manual" | Break words at soft hyphens (U+00AD), adding a hyphen at the line end. Unused soft hyphens are removed. | | [trim] | boolean | false | Remove leading whitespace of each input line. |

License

MIT. See license file.