Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท Streams and readline

Node.js util.styleText() method

Reference for util.styleText(): add colors and text styles with ANSI codes, combine styles in an array, and control stream validation, NO_COLOR and piped output.

util.styleText(format, text) returns text wrapped in the ANSI escape sequences for one or more styles, such as red, bold or bgBlue. It is Node's built-in replacement for small coloring libraries.

By default it looks at the stream you are going to print to (process.stdout) and, if that stream cannot show colors, it returns the plain text. That means node app.js > log.txt stays clean without any code of yours. The style names are the same as the keys of util.inspect.colors.

NODE
import { styleText } from "node:util";

console.log(styleText("green", "ready"));
console.log(styleText(["bold", "red"], "failed"));

Try it

Node.js The escape codes behind the colors

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js A small logger and invalid input

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

NODE
util.styleText(
  format: string | string[],
  text: string,
  options?: { validateStream?: boolean; stream?: Stream }
): string
Name Description
format A style name, or an array of names applied together. Names come from util.inspect.colors: bold, dim, italic, underline, inverse, strikethrough, red, green, blue, bgRed, redBright, gray and more.
text The string to style.
options.validateStream Default true: skip the codes when stream does not support colors. false always adds them.
options.stream The stream to check. Defaults to process.stdout.

Returns: the styled string, or text unchanged when validation says the stream has no colors.

Errors and edge cases:

  • An unknown style name throws ERR_INVALID_ARG_VALUE; the message lists all valid names.
  • A non-string text throws ERR_INVALID_ARG_TYPE.
  • Styles are closed with the matching reset code, so styled strings can be nested or concatenated safely.

Usage notes

  • Check the stream you really write to. For messages printed with console.error(), pass { stream: process.stderr }, since stdout and stderr can differ.
  • The check respects the usual color environment variables (NO_COLOR, FORCE_COLOR, NODE_DISABLE_COLORS) and whether the stream is a terminal.
  • Use validateStream: false only for tests or when you add codes deliberately, for example to show them in documentation.
  • Escape codes make strings longer than they look. Use util.stripVTControlCharacters() before measuring width or padding.
  • Background styles start with bg, bright variants end with Bright (redBright, bgBlueBright), and a few aliases exist (gray and grey).
  • util.styleText() was added in Node.js 20.12 and 21.7, and became stable in Node.js 22.13 and 23.5.