is-term-dark

Detect whether the current terminal background is dark by querying OSC 11.

The package is ESM-only and works in Node.js and Bun terminals that support the OSC 11 background-color query.

Install

npm install is-term-dark

bun add is-term-dark

Usage

import { isTermDark } from "is-term-dark";

const result = await isTermDark();

if (result === null) {
  console.log("Could not detect terminal background.");
} else if (result) {
  console.log("Dark terminal background");
} else {
  console.log("Light terminal background");
}

API

isTermDark(options?)

Returns Promise<boolean | null>.

• true: terminal background appears dark
• false: terminal background appears light
• null: not running in a TTY, the terminal does not answer OSC 11, or the request times out

options:

• timeoutMs?: number defaults to 1000

The legacy isTermDark(timeoutMs) form is still supported for one release cycle, but it is deprecated.

Notes

• The package needs a real TTY. It will return null in non-interactive environments.
• Some terminals do not support OSC 11 and will also return null.
• The published package ships prebuilt files from dist/, so consumers do not need TypeScript or Bun installed.