CLI Cursor

CLI Cursor provides a simple, reliable API for controlling the visibility of the CLI cursor in terminal applications. It uses ANSI escape sequences to show and hide the cursor, with automatic TTY detection to prevent errors in non-terminal environments.

Package Information

• Package Name: cli-cursor
• Package Type: npm
• Language: JavaScript (ES Modules)
• Installation: npm install cli-cursor

Core Imports

import cliCursor from "cli-cursor";

For CommonJS environments:

const cliCursor = require("cli-cursor");

Basic Usage

import cliCursor from "cli-cursor";

// Hide the cursor for a loading animation
cliCursor.hide();
console.log("Loading...");

// Show the cursor when done
setTimeout(() => {
  cliCursor.show();
  console.log("Complete!");
}, 2000);

// Toggle based on a condition
const isLoading = true;
cliCursor.toggle(isLoading); // Will hide cursor if isLoading is true

Capabilities

Show Cursor

Displays the CLI cursor using ANSI escape sequence \u001B[?25h.

/**
 * Show cursor
 * @param {NodeJS.WritableStream} [stream=process.stderr] - Stream to write to
 * @returns {void}
 */
cliCursor.show(stream?): void

Parameters:

• stream (optional): NodeJS.WritableStream - The writable stream to write ANSI sequences to. Defaults to process.stderr.

Behavior:

• Only writes to the stream if stream.isTTY is true
• Sets internal cursor visibility state to visible
• No-op in non-TTY environments

Hide Cursor

Conceals the CLI cursor using ANSI escape sequence \u001B[?25l and ensures graceful restoration on process exit.

/**
 * Hide cursor
 * @param {NodeJS.WritableStream} [stream=process.stderr] - Stream to write to
 * @returns {void}
 */
cliCursor.hide(stream?): void

Parameters:

• stream (optional): NodeJS.WritableStream - The writable stream to write ANSI sequences to. Defaults to process.stderr.

Behavior:

• Calls restoreCursor() from the restore-cursor dependency for graceful exit handling
• Only writes to the stream if stream.isTTY is true
• Sets internal cursor visibility state to hidden
• No-op in non-TTY environments

Toggle Cursor

Toggles cursor visibility or forces a specific state based on a boolean parameter.

/**
 * Toggle cursor visibility
 * @param {boolean} [force] - Force show (true) or hide (false) state
 * @param {NodeJS.WritableStream} [stream] - Stream to write to
 * @returns {void}
 */
cliCursor.toggle(force?, stream?): void

Parameters:

• force (optional): boolean - When provided, forces cursor to show (true) or hide (false) regardless of current state
• stream (optional): NodeJS.WritableStream - The writable stream passed to show/hide methods

Behavior:

• If force parameter is provided, it represents the desired hidden state (true = show cursor, false = hide cursor)
• If force is not provided, toggles between current show/hide state
• Internally calls show() or hide() methods with the provided stream

Usage Examples:

// Toggle between states
cliCursor.toggle(); // If currently visible, will hide; if hidden, will show

// Force specific states
cliCursor.toggle(true);  // Force show cursor (force=true means "force to show")
cliCursor.toggle(false); // Force hide cursor (force=false means "force to hide")

// Use with custom stream
cliCursor.toggle(true, process.stdout);

Environment Compatibility

The package includes automatic TTY detection to ensure safe operation across different environments:

• Terminal environments: Full functionality with ANSI escape sequences
• Non-TTY environments: All methods are no-ops, preventing errors
• Process exit handling: Cursor is gracefully restored when process exits unexpectedly

Dependencies

• restore-cursor (^5.0.0): Ensures cursor is restored on process exit