terminal-theme

🎨 Use a color theme for your code's terminal output


Keywords
colors, color, option, config, configuration, theme, chalk, kleur, ansi, rgb, terminal, tty, shell, bash, cli, es6, javascript, nodejs, library, windows
License
Apache-2.0
Install
npm install terminal-theme@4.0.0

Documentation

Codecov Build Node Twitter Medium

🎨 Use a color theme for your code's terminal output.

A color theme enforces consistency and simplifies updating styles.

Your code specifies the default theme: styles and categories associated to them. Users can then optionally override it.

This supports 256 colors, Truecolor and terminal colors detection, thanks to chalk.

Example

import terminalTheme from 'terminal-theme'

// Any category/key is possible
const defaultTheme = {
  error: 'red bold',
  success: 'green',
  title: 'white bold',
  // Truecolor is supported
  subtitle: 'rgb-150-100-100',
}

const exampleFunction = async function () {
  const { error, success, title, subtitle } = await terminalTheme(defaultTheme)
  console.log(success('example')) // Print in green color
}

User theme

Users can override the defaultTheme by creating a terminal-theme.yml in the current or any parent directory.

error: yellow bold
success: cyan

Or programmatically:

import terminalTheme from 'terminal-theme'

const exampleFunction = async function (userTheme) {
  const { error, success, title, subtitle } = await terminalTheme({
    ...defaultTheme,
    ...userTheme,
  })
  console.log(success('example'))
}

Install

npm install terminal-theme

This package is an ES module and must be loaded using an import or import() statement, not require().

API

terminalTheme(defaultTheme, options?)

defaultTheme: object
options: object
Return value: Promise<object>

defaultTheme

The defaultTheme argument is an object where each:

  • Key is a category with consistent styles. Examples include error, success, link, header, etc.
  • Value is a space-separated list of styles. Some styles require dash-separated arguments.
const defaultTheme = {
  // Single style, without arguments
  success: 'green',
  // Single style, with arguments
  warning: 'rgb-226-126-26',
  // Multiple styles
  error: 'red bold',
}

Return value

The return value is a promise resolving to an object where each:

  • Key is a category defined in the theme.
  • Value is a function applying styles to a string.
import terminalTheme from 'terminal-theme'

const exampleFunction = async function () {
  const { error, success } = await terminalTheme({
    error: 'red',
    success: 'green',
  })
  console.log(success('example'))
}

options

colors

Type: boolean
Default: undefined

Whether colors should be enabled/disabled, regardless of terminal support. Colors support is automatically detected, so this is only meant to override that default behavior.

stream

Type: Stream
Default: process.stdout

Stream used to detect colors support. This should be the file or terminal where the colors are output.

cwd

Type: string
Default: process.cwd()

Current directory. Used when looking for terminal-theme.yml.

Available styles

# Standard styles
bold underline inverse reset

# Those styles do not always work on Windows
dim italic hidden strikethrough

# Hidden when the terminal does not support colors
visible

# Basic colors
black red green yellow blue magenta cyan white gray
blackBright redBright greenBright yellowBright blueBright
magentaBright cyanBright whiteBright

# Advanced colors
hex-ffffff
rgb-255-255-255

# Background colors
bgBlack bgRed bgGreen bgYellow bgBlue bgMagenta bgCyan bgWhite bgGray
bgBlackBright bgRedBright bgGreenBright bgYellowBright bgBlueBright
bgMagentaBright bgCyanBright bgWhiteBright
bgHex-* bgRgb-*

See also

Support

For any question, don't hesitate to submit an issue on GitHub.

Everyone is welcome regardless of personal background. We enforce a Code of conduct in order to promote a positive and inclusive environment.

Contributing

This project was made with ❤️. The simplest way to give back is by starring and sharing it online.

If the documentation is unclear or has a typo, please click on the page's Edit button (pencil icon) and suggest a correction.

If you would like to help us fix a bug or add a new feature, please check our guidelines. Pull requests are welcome!