{"id":16785,"library":"cli-cursor","title":"CLI Cursor Toggle","description":"cli-cursor is a lightweight utility that provides a simple API for showing, hiding, and toggling the command-line interface cursor. Its primary function is to manage cursor visibility in terminal applications, with a notable feature of gracefully restoring the cursor's state upon process exit, preventing a permanently hidden cursor. The current stable version is 5.0.0, which requires Node.js 18 or higher. Releases are typically driven by updates to Node.js LTS versions and the transition to pure ESM, rather than a fixed cadence. Key differentiators include its robust cursor restoration mechanism (powered by `restore-cursor`) and a minimalist, focused API, making it a reliable choice for CLI tools needing precise cursor control.","status":"active","version":"5.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/sindresorhus/cli-cursor","tags":["javascript","cli","cursor","ansi","toggle","display","show","hide","term","typescript"],"install":[{"cmd":"npm install cli-cursor","lang":"bash","label":"npm"},{"cmd":"yarn add cli-cursor","lang":"bash","label":"yarn"},{"cmd":"pnpm add cli-cursor","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Handles the graceful restoration of the CLI cursor upon process exit, preventing it from remaining hidden.","package":"restore-cursor","optional":false}],"imports":[{"note":"Since v4.0.0, this package is pure ESM and must be imported using `import`. CommonJS `require()` is not supported.","wrong":"const cliCursor = require('cli-cursor');","symbol":"cliCursor","correct":"import cliCursor from 'cli-cursor';"},{"note":"The API methods (`hide`, `show`, `toggle`) are properties of the default exported object, not named exports.","wrong":"import { hide } from 'cli-cursor';","symbol":"cliCursor.hide","correct":"import cliCursor from 'cli-cursor';\ncliCursor.hide();"},{"note":"The `toggle` method accepts an optional `force` boolean argument to explicitly show or hide the cursor, and an optional `stream`.","symbol":"cliCursor.toggle","correct":"import cliCursor from 'cli-cursor';\ncliCursor.toggle(true);"}],"quickstart":{"code":"import cliCursor from 'cli-cursor';\nimport process from 'node:process';\n\nconsole.log('Cursor is visible. Hiding now...');\ncliCursor.hide();\n\n// Simulate some work\nsetTimeout(() => {\n  console.log('Performing some background task...');\n}, 1000);\n\n// Toggle cursor visibility based on a condition\nconst shouldShowCursor = process.env.SHOW_CURSOR === 'true';\n\nsetTimeout(() => {\n  console.log(`Toggling cursor to ${shouldShowCursor ? 'visible' : 'hidden'}...`);\n  cliCursor.toggle(shouldShowCursor);\n\n  // Ensure cursor is shown before exiting in case of manual toggle logic\n  // This is handled gracefully by `restore-cursor` on process exit, but explicit is sometimes clearer.\n  setTimeout(() => {\n    cliCursor.show(); // Ensure cursor is visible before application ends\n    console.log('Cursor should now be visible. Exiting.');\n  }, 1500);\n\n}, 2000);\n","lang":"typescript","description":"Demonstrates hiding and toggling the CLI cursor, with graceful restoration on exit and explicit showing before the application terminates."},"warnings":[{"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+).","message":"Version 5.0.0 of `cli-cursor` requires Node.js 18 or higher. Projects running on older Node.js versions will encounter compatibility issues.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Migrate your project to use ES modules (`import`) or dynamically import the package. If using CommonJS, pin `cli-cursor` to `^3.1.0`.","message":"`cli-cursor` became a pure ESM package in version 4.0.0. This means it no longer supports CommonJS `require()` syntax.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Upgrade Node.js to version 12.20 or higher, or downgrade `cli-cursor` to `^3.1.0` if Node.js 8+ is required.","message":"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.","severity":"breaking","affected_versions":">=4.0.0 <5.0.0"},{"fix":"Upgrade Node.js to version 8 or higher, or use `cli-cursor@^2.x.x`.","message":"Version 3.0.0 introduced a minimum Node.js requirement of 8. This might break projects on very old Node.js runtimes.","severity":"breaking","affected_versions":">=3.0.0 <4.0.0"},{"fix":"Include `cliCursor.show()` in your application's cleanup logic, especially before process exits that might not trigger `restore-cursor`'s hooks.","message":"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.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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).","cause":"Attempting to `require()` `cli-cursor` in a CommonJS module after version 4.0.0, which is pure ESM.","error":"ERR_REQUIRE_ESM"},{"fix":"Ensure you are using `import cliCursor from 'cli-cursor';` and then calling `cliCursor.hide()`, `cliCursor.show()`, or `cliCursor.toggle()`.","cause":"Incorrectly importing `hide` or other methods as named exports instead of accessing them from the default exported object.","error":"TypeError: cliCursor.hide is not a function"},{"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.","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.","error":"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."},{"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.","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).","error":"SyntaxError: Cannot use import statement outside a module"}],"ecosystem":"npm","meta_description":null}