Ninja Parading Musically

    TypeScript icon, indicating that this package has built-in type declarations

    4.0.4 • Public • Published


    A node module for text wrapping into streams that supports 24bit color SGR codes.

    Publishing Status

    Travis Rollup

    Development Status

    Snyk Code-Climate Code-Climate Coverage



    v4 Breaking change The CLI command has been seperated into it's own repo truwrap-cli

    Many current tty text wrapping solutions have issues with the 'long' and currently 'non-standard' RGB SGR codes (i.e ^[[38;2;204;51;66m). This meant that, while it's possible to have wonderful, rich, full gamut colours and the aesthetic data visualisations it entails, it comes at the price of painful typography and corrupted console displays as text is broken up, unnaturally wrapped and becoming unreadable as the SGR codes are dashed against the rocks of 1980's shortsightedness, confusing your terminal and ever so slightly breaking the heart of design aware coders and administrators everywhere.

    Clearly this is unnacceptable!

    Previously, the only solution was to take a last, long whistful look at how great console colour could be, before going back to the, at best, 256 colours of the xterm pallette, with it's lack of useful greens and overly dark purples, or, for some, the even more cruelly devastating 16 colours of the ansi pallette, before heading to the stationary cupboard for a bit of a cry.

    But weep no more!

    Developed as part of our internal data visualisation system, where having the fidelity of 24 bit colour and embedded images (currently macOS iTerm only) was a huge advantage.



    npm install --save @thebespokepixel/truwrap
    import {truwrap} from '@thebespokepixel/truwrap'
    var writer = truwrap({
      left: 2,
      right: 2,
      mode: 'soft',
      outStream: process.stderr
    var contentWidth = writer.getWidth()
    writer.write("Some text to write...", "...and some more.")
    writer.write("A new paragraph, if not implicitly present.")
    writer.end() // Close the stream

    mode can be set to the following values:

    • soft: words are broken before the column width, giving a left justified appearance.
    • hard: words are split at the column width.
    • keep: lines longer than the column width are kept.
    • container: left and right margins are ignored, giving a full width line.

    As outStream was specified, wrapped output is written directly to the stream.


    If your terminal suppots them, you can add images into the wrapped output text.

    To ensure that images are not used by default you need to set the env var TERM_IMAGES=enabled in your shell. See term-ng for details.

    import {truwrap, createImage} from '@thebespokepixel/truwrap'
    const image = createImage({
      name: 'test',
      file: join(dirname(fileURLToPath(import.meta.url)), '../media/test.png'),
      width: 'auto', // Number of chars wide you'd like image. 'auto' to take it from the image/set height.
      height: 1,     // Number of lines the image will take
      space: '   '   // A text string that is printed under the image so you can flow the wrapped text around it.
    var renderer = truwrap({
      mode: 'container'
      nobreak: true,  // Don't add a linebreak after the image.
      stretch: false, // If true, distort the image the image to fit the width/height
      align: 1        // How many lines to move back up after printing the image.
      spacing: ' '    // A string to print after realigning the cursor after printing the image.

    As no outStream was specified truwrap.end() returns the wrapped text.


    import {truwrap, parsePanel} from '@thebespokepixel/truwrap'
    var writer = truwrap({
      left: 2,
      right: 2,
      mode: 'soft',
      outStream: process.stderr
    const panelSource = parsePanel(
      'One|Two|Three|Four', //Input text with column delimiters
      '|',                  // Column delimiter
      writer.getWidth()     // Total width (chars) to make columns across
    const panelOptions = {
      maxLineWidth: writer.getWidth(),    // Maximum line width
      showHeaders: false,                 // Show colum headers
      truncate: false,                    // Truncate columns if too wide
      config: panelSource.configuration   // Get config information from parsePanel()
    writer.panel(panelSource.content, panelOptions)
    writer.end() //Close stream


    For advanced 24bit colour handling see thebespokepixel/trucolor and npm trucolor.


    Full documentation can be found at


    npm i truwrap

    DownloadsWeekly Downloads






    Unpacked Size

    41.7 kB

    Total Files


    Last publish


    • thebespokepixel