CLI Cursor Toggle

Common errors

• ERR_REQUIRE_ESM

  cause Attempting to `require()` `cli-cursor` in a CommonJS module after version 4.0.0, which is pure ESM.
  fix Change `const cliCursor = require('cli-cursor');` to `import cliCursor from 'cli-cursor';` and ensure your project is configured for ES modules (e.g., `"type": "module"` in `package.json` or using `.mjs` extension).

• TypeError: cliCursor.hide is not a function

  cause Incorrectly importing `hide` or other methods as named exports instead of accessing them from the default exported object.
  fix Ensure you are using `import cliCursor from 'cli-cursor';` and then calling `cliCursor.hide()`, `cliCursor.show()`, or `cliCursor.toggle()`.

• Error [ERR_UNSUPPORTED_DIR_IMPORT]: Named export 'default' not found. The requested module 'cli-cursor' is an ECMAScript module, and does not provide a default export.

  cause This error can occur if a bundler or specific import configuration misinterprets the default export, or if an older environment has issues with ESM interoperability. Sometimes this happens with incorrect TypeScript `esModuleInterop` settings or when mixing CJS and ESM without proper transpilation.
  fix Verify your `tsconfig.json` includes `"esModuleInterop": true`, `"allowSyntheticDefaultImports": true`, and ensure your bundler (if any) is configured correctly for ESM. Alternatively, try `import * as cliCursor from 'cli-cursor';` though `import cliCursor from 'cli-cursor';` should work for a default export.

• SyntaxError: Cannot use import statement outside a module

  cause Attempting to use `import` syntax in a file that is treated as a CommonJS module (e.g., a `.js` file without `"type": "module"` in `package.json`, or a `.cjs` file).
  fix Either rename your file to `.mjs`, add `"type": "module"` to your `package.json`, or configure your build system (e.g., Babel, TypeScript) to transpile ESM to CommonJS if your runtime environment is strictly CommonJS.

Warnings

• breaking Version 5.0.0 of `cli-cursor` requires Node.js 18 or higher. Projects running on older Node.js versions will encounter compatibility issues.
  Fix: Upgrade Node.js to version 18 or higher, or pin `cli-cursor` to a compatible older version (e.g., `^4.0.0` for Node.js 12.20+).
• breaking `cli-cursor` became a pure ESM package in version 4.0.0. This means it no longer supports CommonJS `require()` syntax.
  Fix: Migrate your project to use ES modules (`import`) or dynamically import the package. If using CommonJS, pin `cli-cursor` to `^3.1.0`.
• breaking Version 4.0.0 of `cli-cursor` requires Node.js 12.20 or higher. Running on older Node.js versions will result in runtime errors.
  Fix: Upgrade Node.js to version 12.20 or higher, or downgrade `cli-cursor` to `^3.1.0` if Node.js 8+ is required.
• breaking Version 3.0.0 introduced a minimum Node.js requirement of 8. This might break projects on very old Node.js runtimes.
  Fix: Upgrade Node.js to version 8 or higher, or use `cli-cursor@^2.x.x`.
• gotcha While `cli-cursor` gracefully restores the cursor on process exit, unexpected termination (e.g., `kill -9`) might leave the cursor hidden. It's good practice to ensure `cliCursor.show()` is called before explicit application termination if you hide it.
  Fix: Include `cliCursor.show()` in your application's cleanup logic, especially before process exits that might not trigger `restore-cursor`'s hooks.

Install

• npm install cli-cursor npm
• yarn add cli-cursor yarn
• pnpm add cli-cursor pnpm

Imports

• cliCursor
  wrong:

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

  correct:

  import cliCursor from 'cli-cursor';

  Since v4.0.0, this package is pure ESM and must be imported using `import`. CommonJS `require()` is not supported.
• cliCursor.hide
  wrong:

  import { hide } from 'cli-cursor';

  correct:

  import cliCursor from 'cli-cursor';
  cliCursor.hide();

  The API methods (`hide`, `show`, `toggle`) are properties of the default exported object, not named exports.
• cliCursor.toggle

  import cliCursor from 'cli-cursor';
  cliCursor.toggle(true);

  The `toggle` method accepts an optional `force` boolean argument to explicitly show or hide the cursor, and an optional `stream`.

Quickstart

Demonstrates hiding and toggling the CLI cursor, with graceful restoration on exit and explicit showing before the application terminates.

import cliCursor from 'cli-cursor';
import process from 'node:process';

console.log('Cursor is visible. Hiding now...');
cliCursor.hide();

// Simulate some work
setTimeout(() => {
  console.log('Performing some background task...');
}, 1000);

// Toggle cursor visibility based on a condition
const shouldShowCursor = process.env.SHOW_CURSOR === 'true';

setTimeout(() => {
  console.log(`Toggling cursor to ${shouldShowCursor ? 'visible' : 'hidden'}...`);
  cliCursor.toggle(shouldShowCursor);

  // Ensure cursor is shown before exiting in case of manual toggle logic
  // This is handled gracefully by `restore-cursor` on process exit, but explicit is sometimes clearer.
  setTimeout(() => {
    cliCursor.show(); // Ensure cursor is visible before application ends
    console.log('Cursor should now be visible. Exiting.');
  }, 1500);

}, 2000);