{"id":16985,"library":"elegant-spinner","title":"Elegant CLI Spinner Frames","description":"elegant-spinner provides a simple, elegant set of ASCII frames designed for creating visual loading indicators in interactive command-line interface (CLI) applications. The current stable version is 3.0.0. This package itself does not handle the animation logic; rather, it supplies the individual spinner frames that an external utility (like `log-update` or `ora`) can iterate through to create an animated effect. Its release cadence is tied to Node.js compatibility updates and essential maintenance, rather than rapid feature development. A key differentiator is its minimalism, focusing solely on the spinner frames. However, for most use cases requiring a full-fledged animated spinner, the `ora` package is recommended as it bundles `elegant-spinner` and manages the animation loop automatically. It supports modern Node.js environments and is pure ESM since version 3.0.0, with TypeScript definitions available since version 2.0.0.","status":"maintenance","version":"3.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/sindresorhus/elegant-spinner","tags":["javascript","ansi","terminal","console","cli","string","log","logging","spinner"],"install":[{"cmd":"npm install elegant-spinner","lang":"bash","label":"npm"},{"cmd":"yarn add elegant-spinner","lang":"bash","label":"yarn"},{"cmd":"pnpm add elegant-spinner","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Commonly used with elegant-spinner to render animated output by overwriting the terminal line.","package":"log-update","optional":false}],"imports":[{"note":"Since v3.0.0, this package is pure ESM and must be imported using ES modules syntax. CommonJS `require()` will fail.","wrong":"const elegantSpinner = require('elegant-spinner');","symbol":"elegantSpinner","correct":"import elegantSpinner from 'elegant-spinner';"},{"note":"The default import is a factory function that returns an iterator for spinner frames. Call it to get the next frame string.","symbol":"FrameIterator","correct":"import elegantSpinner from 'elegant-spinner';\nconst frame = elegantSpinner();\n// frame() returns the next string frame"}],"quickstart":{"code":"import elegantSpinner from 'elegant-spinner';\nimport logUpdate from 'log-update';\n\nconst spinnerFrames = elegantSpinner();\nlet counter = 0;\nconst interval = setInterval(() => {\n  const currentFrame = spinnerFrames();\n  logUpdate(`Loading ${currentFrame} ${counter++}%`);\n  if (counter > 100) {\n    clearInterval(interval);\n    logUpdate.done();\n    console.log('Loading complete!');\n  }\n}, 50);\n","lang":"javascript","description":"Demonstrates how to import the `elegantSpinner` function and use it with `log-update` to render a basic animated spinner in the terminal, manually updating frames every 50ms and showing a progress percentage."},"warnings":[{"fix":"Migrate your project to use ES modules (`import`/`export`) or use an older version of the package if CommonJS is strictly required.","message":"Version 3.0.0 and above is pure ESM (ECMAScript Modules). CommonJS `require()` statements are no longer supported and will result in an error.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Upgrade your Node.js runtime to a compatible version.","message":"Version 3.0.0 requires Node.js 12.20.0, 14.13.1, or >=16.0.0. Older Node.js versions are not supported.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"For full animation, consider using `ora`. If sticking with `elegant-spinner`, you'll need to manually implement the animation loop using tools like `log-update` and `setInterval`.","message":"This package only provides the spinner frames. It does not handle the animation logic (e.g., setting intervals, clearing output). For a complete, animated spinner solution, the `ora` package is generally recommended as it wraps `elegant-spinner` and handles animation automatically.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure your Node.js version meets the requirement for the specific `elegant-spinner` version you are using. For versions 2.x, Node.js 8+ is needed.","message":"Version 2.0.0 required Node.js 8 or higher. Prior versions supported older Node.js environments.","severity":"breaking","affected_versions":">=2.0.0 <3.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Change your import statement from `const elegantSpinner = require('elegant-spinner');` to `import elegantSpinner from 'elegant-spinner';` and ensure your project is configured for ES modules (e.g., `\"type\": \"module\"` in package.json).","cause":"Attempting to import `elegant-spinner` using CommonJS `require()` syntax in a Node.js environment with version 3.0.0 or later.","error":"ERR_REQUIRE_ESM"}],"ecosystem":"npm","meta_description":null}