supports-color

supports-color is a lightweight JavaScript library that detects whether a terminal supports color output. It provides intelligent color support detection across different environments including Node.js and browsers, analyzing terminal streams to determine color capabilities ranging from basic 16-color support to full truecolor (16 million colors).

Package Information

• Package Name: supports-color
• Package Type: npm
• Language: JavaScript (ES modules)
• Installation: npm install supports-color

Core Imports

import supportsColor from "supports-color";

For the createSupportsColor function:

import supportsColor, { createSupportsColor } from "supports-color";

For CommonJS:

const supportsColor = require("supports-color");
const { createSupportsColor } = require("supports-color");

Basic Usage

import supportsColor from "supports-color";

// Check if terminal supports color
if (supportsColor.stdout) {
  console.log("Terminal stdout supports color");
  console.log(`Color level: ${supportsColor.stdout.level}`);
}

// Check specific color capabilities
if (supportsColor.stdout.has256) {
  console.log("Terminal supports 256 colors");
}

if (supportsColor.stderr.has16m) {
  console.log("Terminal stderr supports 16 million colors (truecolor)");
}

// Custom stream analysis
import { createSupportsColor } from "supports-color";

const customSupport = createSupportsColor(process.stdout);
if (customSupport) {
  console.log(`Custom stream color level: ${customSupport.level}`);
}

Capabilities

Pre-analyzed Color Support

The default export provides pre-analyzed color support for standard streams.

interface SupportsColor {
  stdout: ColorInfo;
  stderr: ColorInfo;
}

const supportsColor: SupportsColor;

Properties:

• stdout: ColorInfo - Color support information for stdout stream
• stderr: ColorInfo - Color support information for stderr stream

Custom Stream Analysis

Creates color support analysis for arbitrary streams with optional configuration.

/**
 * Analyze color support for a custom stream
 * @param stream - Optional WriteStream to analyze (defaults to stdout-like behavior)
 * @param options - Optional configuration options
 * @returns Color support information or false if no color support
 */
function createSupportsColor(stream?: import('node:tty').WriteStream, options?: Options): ColorInfo;

Parameters:

• stream (optional): import('node:tty').WriteStream - The stream to analyze for color support
• options (optional): Options - Configuration options for the analysis

Returns: ColorInfo - Color support information or false

Usage Examples:

import { createSupportsColor } from "supports-color";

// Analyze stdout with default settings
const stdoutSupport = createSupportsColor(process.stdout);

// Analyze stderr without flag sniffing
const stderrSupport = createSupportsColor(process.stderr, { sniffFlags: false });

// Analyze without providing a stream (uses default behavior)
const defaultSupport = createSupportsColor();

Types

ColorInfo Type

/**
 * Color support information - either a ColorSupport object or false
 */
type ColorInfo = ColorSupport | false;

ColorSupport Interface

/**
 * Object describing terminal color capabilities
 */
interface ColorSupport {
  /** The color support level (0-3) */
  level: ColorSupportLevel;
  /** Whether basic 16 colors are supported */
  hasBasic: boolean;
  /** Whether ANSI 256 colors are supported */
  has256: boolean;
  /** Whether Truecolor 16 million colors are supported */
  has16m: boolean;
}

ColorSupportLevel Type

/**
 * Numeric representation of color support levels
 * - 0: All colors disabled
 * - 1: Basic 16 colors support
 * - 2: ANSI 256 colors support  
 * - 3: Truecolor 16 million colors support
 */
type ColorSupportLevel = 0 | 1 | 2 | 3;

Options Interface

/**
 * Configuration options for createSupportsColor function
 */
interface Options {
  /** Whether process.argv should be sniffed for --color and --no-color flags (default: true) */
  readonly sniffFlags?: boolean;
}

Environment Variables

The library responds to various environment variables for controlling color behavior:

• FORCE_COLOR: Override color detection
  • '0' or 'false': Force disable colors
  • '1' or 'true': Force basic color support
  • '2': Force 256 color support
  • '3': Force truecolor support
• TERM: Terminal type detection (e.g., 'xterm-256color', 'dumb')
• COLORTERM: Color terminal indicator (e.g., 'truecolor')
• CI: Continuous integration detection
• TRAVIS, CIRCLECI, APPVEYOR, GITLAB_CI, BUILDKITE, DRONE: CI-specific variables
• GITHUB_ACTIONS, GITEA_ACTIONS: GitHub/Gitea Actions detection
• TEAMCITY_VERSION: TeamCity version detection
• TERM_PROGRAM, TERM_PROGRAM_VERSION: Terminal program detection (e.g., iTerm.app)
• TF_BUILD, AGENT_NAME: Azure DevOps detection

Command-Line Flags

The library automatically detects and responds to command-line flags (when sniffFlags is true):

• Enable color: --color, --colors, --color=true, --color=always
• Disable color: --no-color, --no-colors, --color=false, --color=never
• Force 256 colors: --color=256
• Force truecolor: --color=16m, --color=full, --color=truecolor

Platform Differences

Node.js Environment

• Full detection logic including TTY analysis, environment variables, and platform-specific behavior
• Windows-specific color support detection based on OS build numbers
• CI system detection and handling

Browser Environment

• Chrome/Chromium-specific detection using navigator.userAgent and navigator.userAgentData
• Simplified color level detection (level 0, 1, or 3)
• No environment variable or command-line flag support

Error Handling

The library is designed to gracefully handle various environments and never throws errors. It returns false when color support cannot be determined or is explicitly disabled.