terminal-font

TerminalFont.JS

[TOC]

Terminal font library for Node.JS, providing support for colors, font styles and more in Node.JS console.

Overview

• 🐰 Support colors, font weight, font styles and more
• 🐰 Support 24-bit true colors (by RGB or hex color codes)
• 🐰 Support font styles combination
• 🐰 Support CSS-like settings
• 🐰 Easy to use and extend
• 🐰 Full typescript support

Installation

npm install terminal-font

If you are using Yarn, you can use

yarn add terminal-font

Usage

Quick Overview

Multiple invocation ways are supported, just depending on what you like:

const { font } = require('terminal-font');

console.log(font().green().apply('Green text'));
console.log(font().bold().red().bgCyan().italic().apply('Complex styles!'));
console.log(
  font().set('bold', 'italic', 'magenta').apply('Yet another way to use')
);
console.log(
  font()
    .set({
      color: font.rgb(245, 169, 184),
      backgroundColor: font.hexColor('#47a9fa'),
    })
    .apply('Fallen angel, distant heaven.')
);

The result is:

Colors

To set the color or the background color of the text, simply use the format like

font().red().apply('Red text');
font().bgBlue().apply('Text with blue background');

which uses the pre-defined colors by the terminal (see pre-defined colors) or

font()
  .set({
    color: font.rgb(245, 169, 184),
    backgroundColor: font.hexColor('#47a9fa'),
  })
  .apply('Fallen angel, distant heaven.');

to use the 24-bit true colors. Specially, font().default() or font().bgDefault() set the color or background color of the text to the default color defined by the terminal.

NOTICE: True color mode is supported by most of the terminal emulators recently, however, not all terminal emulator supports 24-bit true color mode. A classical counterexample is the Terminal.App in MacOS, which may map the color into the closet color in 256-colors table, or pre-defined basic colors.

Pre-defined Colors

Recently, Terminal.JS supports the following pre-defined colors:

• black
• red
• green
• yellow
• blue
• magenta
• cyan
• white

If you want to specify a color beyond the pre-defined colors, use the RGB or hex color code form instead. Moreover, more pre-defined colors will be supported in the future, just like what CSS acts.

Styles

To set the styles of the text, use one of the following forms:

font().bold().italic().apply('Italic bold text');
font()
  .set({
    fontStyle: ['faint', 'underline', 'strike'],
  })
  .apply('Another way');

Supported styles include:

• bold
• italic
• faint
• underline
• blink
• strike

Specially, set the font style to regular will clear all styles (colors won't be affected).

Combining Colors and Styles

Chain invocation is supported in TerminalFont.JS, thus you can easily combine the colors and styles with the following form:

font()
  .set({
    color: 'red',
  })
  .bgWhite()
  .set({
    fontStyle: ['italic', 'faint'],
  })
  .blink()
  .strike()
  .underline()
  .apply('Very complex styles');

API

TL;DR;

Function: font

font()

Syntax

  font(): Font;

Creates a new Font object. This is the alias for calling new Font().

font.rgb

Syntax

font.rgb(red: number, green: number, blue: number): RgbObject;

Returns a RgbObject with the given parameters defining the RGB values. Please use this with Font.prototype.set.

font.hexColor

Syntax

font.hexColor(hexCode: string): RgbObject;

Returns a RgbObject with the given hex code, similarily to font.rgb.

Class: Font

An instance of class Font stores and manipulate certian settings of font, and is able to apply these settings to a string.

Font.prototype.set()

Syntax

Font.prototype.set(...FontSettings[]);

Configure the font settings. The arguments can be passed via various ways:

Via string

Sample:

font().set('red', 'italic', 'strike');

Via object

In this way, you need to pass a object with the type FontSettingsObject.

Sample:

font().set({
  color: 'red', // text color
  backgroundColor: 'cyan', // background color
  fontStyle: ['bold', 'italic'], // font style
  options: {
    // options
  },
});

See Options for supported options list.

Font.prototype.apply()

Syntax

Font.prototype.apply(originalString: string): string;

Apply the font settings to a string and returns the new string with font. This operation doesn't change the original string.

Options

Additional options can be set with the form

font().set({
  options: {
    // ...
  },
});

Supported options include:

reset

Type: boolean Defualt: true

This configures whether to reset the colors at the ending of the string. Set this option to false will allow you to use TerminalFont.JS in another way:

const fontSetter = () =>
  font().set({
    options: {
      reset: false,
    },
  });
console.log(
  'Are %snested %sstyles %sawesome %sor %snot?',
  fontSetter().red().apply(''),
  fontSetter().bold().apply(''),
  fontSetter().bgCyan().apply(''),
  fontSetter().strike().apply(''),
  fontSetter().underline().apply('')
);

NOTICE: This is not a recommended way to use TerminalFont.JS, as it may lead to an unexpected result. We will provide more elegant ways to use nested styles in the future.

To-do List

• 🐰 Fallback strategy if terminal doesn't support true color
• 🐰 More pre-defined color
• 🐰 Gradient color support
• 🐰 Render HTML template

License

TerminalFont.JS is licensed under GNU Lesser General Public License 2.1.