pad-without-control-characters

Maintenance status: Maintained. This project is AI-free and bans all AI contributions.

When using String#padStart or String#padEnd with strings that are formatted for terminal display (eg. adding color), you'll quickly discover that the resulting padding length is... not quite right. This happens because terminal styling works with 'control characters' that the terminal doesn't display, but that are still part of the string. It's kind of like the terminal equivalent of HTML tags.

But because JS isn't a terminal and so it doesn't do anything terminal-specific, padEnd and padStart (correctly!) count these 'invisible' characters as normal, and so it believes the string to be longer than it really is. So, it doesn't pad it as much as it should. This makes sense from a JS perspective, but it's really annoying when you're trying to do things like drawing boxes and borders in the terminal!

So, this module fixes that with a variant of padStart and padEnd that doesn't count control characters in the original string's length. It doesn't remove them - they'll still be there in the resulting string. It just adds a different amount of padding.

The semantics of these functions should be the same as those of String#padStart and String#padEnd. If this is not the case, please file a bug!

A note on styling of the padding

NOTE: This module intentionally does not try to understand the meaning of the control characters, and so it doesn't modify them. Because of how these control codes work, that means that padding at the end may be styled (depending on your styling implementation), but padding at the start won't be styled. If you need an entire string including the padding to be styled, you should always make sure to do the padding before the styling, and not the other way around. So:

styleText("red", padWithoutCC.start("your string goes here", 80)) // correct!
// ... instead of ...
padWithoutCC.start(styleText("red", "your string goes here"), 80) // wrong!

Usage example

const { styleText } = require("node:util");
const padWithoutCC = require("pad-without-control-characters");

let style = ["bgGreen", "black", "bold"];

// filled out to 80 columns on the right (but always 2 columns of padding on the other side):
console.log(styleText(style, padWithoutCC.end("  this is your string!  ", 80)));
// and on the left:
console.log(styleText(style, padWithoutCC.start("  this is your string!  ", 80)));

Changelog

1.0.0 (August 20, 2026)

Initial release.