{"id":21224078,"url":"https://github.com/kodie/progress-img","last_synced_at":"2025-07-10T14:31:16.511Z","repository":{"id":57331037,"uuid":"103982168","full_name":"kodie/progress-img","owner":"kodie","description":"Use images as progress bars in the terminal!","archived":false,"fork":false,"pushed_at":"2023-01-06T20:01:21.000Z","size":340,"stargazers_count":19,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-10-16T08:31:53.016Z","etag":null,"topics":["animate","animated","animation","bmp","cli","gif","image","jpeg","jpg","loader","loading","picture","png","progress","progress-bar","tiff"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kodie.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-09-18T19:25:38.000Z","updated_at":"2023-08-27T05:03:51.000Z","dependencies_parsed_at":"2023-02-06T08:31:51.491Z","dependency_job_id":null,"html_url":"https://github.com/kodie/progress-img","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kodie%2Fprogress-img","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kodie%2Fprogress-img/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kodie%2Fprogress-img/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kodie%2Fprogress-img/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kodie","download_url":"https://codeload.github.com/kodie/progress-img/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225640772,"owners_count":17501018,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["animate","animated","animation","bmp","cli","gif","image","jpeg","jpg","loader","loading","picture","png","progress","progress-bar","tiff"],"created_at":"2024-11-20T22:54:56.838Z","updated_at":"2024-11-20T22:54:57.464Z","avatar_url":"https://github.com/kodie.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# progress-img\n[![npm package version](https://img.shields.io/npm/v/progress-img.svg?style=flat-square)](https://www.npmjs.com/package/progress-img)\n[![Travis build status](https://img.shields.io/travis/kodie/progress-img.svg?style=flat-square)](https://travis-ci.org/kodie/progress-img)\n[![npm package downloads](https://img.shields.io/npm/dt/progress-img.svg?style=flat-square)](https://www.npmjs.com/package/progress-img)\n[![index.js file size](https://img.shields.io/github/size/kodie/progress-img/index.js.svg?style=flat-square)](index.js)\n[![code style](https://img.shields.io/badge/code_style-standard-yellow.svg?style=flat-square)](https://github.com/standard/standard)\n[![license](https://img.shields.io/github/license/kodie/progress-img.svg?style=flat-square)](LICENSE.md)\n\n![](https://raw.githubusercontent.com/kodie/progress-img/master/media/preview.gif?raw=true)\n\nUse images as progress bars in the terminal!\n\n## Requirements\n* [Node.js](https://nodejs.org) v4.0 or higher\n\n*[iTerm2](https://iterm2.com) v2.9 or higher is required to display actual images. Otherwise an [ASCII](https://en.wikipedia.org/wiki/ASCII_art) version of the images will be displayed.*\n\n## Installation\n```shell\nnpm install --save progress-img\n```\n\n## Usage\n```javascript\nconst ProgressImg = require('progress-img')\n\nvar progress = new ProgressImg('awesome.gif', {\n  frameThrottle: '500ms',\n  textTop: 'Downloading file...',\n  width: '100%'\n})\n\n// Set progress to a specific frame\nprogress.set(3)\n\n// Set progress to a percentage\nprogress.set('26%')\n\n// Display some text below the image\nprogress.set('52%', { textBottom: 'Please wait...' })\n\n// Clear the progress\nprogress.clear()\n\n// Finish\nprogress.done()\n```\n\n*Note: The `clear()` function is optional, however the `done()` function should always be ran when you are finished with the progress image.*\n\n## Images\nThe first parameter of the initial `ProgressImg` setup function is where you set the image(s) that you would like to use. If one is not supplied, a default one will be used.\n\nThis parameter accepts a string or an array filled with strings that contain either a file path, URL, or image buffer.\n\n## Options\nThese options can be passed as the second parameter to either the initial `ProgressImg` setup, or to the `progress.set` function.\n\n```javascript\nvar options = {\n  image: 'awesome.gif',\n\n  width: 'auto',\n\n  height: 'auto',\n\n  preserveAspectRatio: true,\n\n  expandGifs: false,\n\n  useFallback: true,\n\n  textTop: 'Downloading file...',\n\n  textBottom: 'Please wait...',\n\n  saveOptions: true,\n\n  set: '20%',\n\n  frameThrottle: '500ms',\n\n  output: process.stdout\n}\n```\n\n### image\nThe image(s) to use. Can be used instead of the `image` parameter. (Defaults to `./loader.gif`)\n\n*Note: This option can only be used in the initial `ProgressImg` setup.*\n\n### width\n### height\nThe width and height of the image. Can be one of the following: (Defaults to `auto`)\n\n* `N`: N character cells.\n* `Npx`: N pixels.\n* `N%`: N percent of the session's width or height.\n* `auto`: The image's inherent size will be used to determine an appropriate dimension.\n\n*Note: This option can only be used in the initial `ProgressImg` setup when using the ASCII fallback.*\n\n### preserveAspectRatio\nWhether to preserve the aspect ratio of the image or not. (Defaults to `true`)\n\n### expandGifs\nWhether or not to expand GIFs into separate frames. (Defaults to `true`)\n\n*Note: This option can only be used in the initial `ProgressImg` setup.*\n\n### useFallback\nWhether to use the fallback progress bar regardless if the user is using a supported terminal or not. Great for testing how the fallback progress bar looks or bypassing the terminal check. (Defaults to `null`)\n\n*Note: This option can only be used in the initial `ProgressImg` setup.*\n\n### textTop\n### textBottom\nText to display above or below the image. (Defaults to `null`)\n\n### saveOptions\nWhether to overwrite the options set in the initial `ProgressImg` setup. (Defaults to `false`)\n\n*Note: This option can only be used in the `progress.set` function.*\n\n### set\nThe frame number or percentage to set the progress to. Can be used instead of `set` parameter. Can also be used in the initial `ProgressImg` setup. (Defaults to `null`)\n\n### frameThrottle\nThrottle the frame changes by: (Defaults to `0`)\n\n* `N`: Actual frame count.\n* `N%`: Frame count percentage.\n* `Nms`: Milliseconds since the last frame change.\n\n*Note: `500ms` is recommended for a smoother animation.*\n\n### output\nThe stream to output to. (Defaults to `process.stdout`)\n\n## License\nMIT. See the [License file](LICENSE.md) for more info.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkodie%2Fprogress-img","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkodie%2Fprogress-img","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkodie%2Fprogress-img/lists"}