{"id":24291458,"url":"https://github.com/superjojo140/ascii-bar","last_synced_at":"2025-09-25T17:30:18.941Z","repository":{"id":57184674,"uuid":"304892905","full_name":"superjojo140/ascii-bar","owner":"superjojo140","description":"A lightweight ascii progress bar with spinner and colors","archived":false,"fork":false,"pushed_at":"2020-10-30T11:18:32.000Z","size":300,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-12-13T13:58:27.327Z","etag":null,"topics":["ascii","cli","console","nodejs","progressbar"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/ascii-bar","language":"TypeScript","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/superjojo140.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-10-17T14:13:24.000Z","updated_at":"2024-09-17T22:06:44.000Z","dependencies_parsed_at":"2022-09-14T09:01:05.415Z","dependency_job_id":null,"html_url":"https://github.com/superjojo140/ascii-bar","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/superjojo140%2Fascii-bar","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/superjojo140%2Fascii-bar/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/superjojo140%2Fascii-bar/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/superjojo140%2Fascii-bar/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/superjojo140","download_url":"https://codeload.github.com/superjojo140/ascii-bar/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234164214,"owners_count":18789475,"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":["ascii","cli","console","nodejs","progressbar"],"created_at":"2025-01-16T14:33:08.451Z","updated_at":"2025-09-25T17:30:18.177Z","avatar_url":"https://github.com/superjojo140.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ascii-bar\n\n![Screenshot - made with termToSvg](https://raw.githubusercontent.com/superjojo140/ascii-bar/main/example/screenshot.svg)\n\n- [How to use](#how-to-use)\n- [Configuration](#configuration)\n    - [Template String](#template-string)\n    - [Options](#options)\n    - [Spinner](#spinner)\n- [API Methods and properties](#api-methods-and-properties)\n    - [Methods](#methods)\n    - [Properties](#properties)\n\n## Why is it cool?\n\n- 🚀 Extreme **lightweight** (\u003c50kB) and **zero dependencies**\n- ⭕ **Fancy Spinners** (automatic ascii fallback for windows)\n- 🎨 **Colors** and Emoji support (if your terminal can display this)\n- 🖋️ Intuitive styling via **templateString**\n- ⏰ Calculation and pretty printing of overall progress time and **time to finish**\n- 🔧 Extreme customizable (configure output stream, timing calculation, spinner behavior,...)\n- 📖 Typescript types and documentation\n\n## How to use\n\n#### Installation\n\n````shell\n    npm install ascii-bar\n````\n\n#### Basic Usage\n\n````javascript\n    const AsciiBar = require('ascii-bar').default;\n\n    const bar = new AsciiBar();\n\n    //in your long during task\n    bar.update(numberOfDoneThings,someInfoAboutCurrentTask);\n````\n\n#### Using with `import`\n\n````javascript\n    import AsciiBar from 'ascii-bar'\n````\n\nFor more examples see [examples folder](https://github.com/superjojo140/ascii-bar/tree/main/example).\n\n## Configuration\n\n### Template string\n\nThe `templateString` has the greatest influence on the appearance. It allows you to define which elements your status bar contains and how they are arranged.\nTo use a special `templateString` use it as a parameter in the constructor:\n\n````javascript\n    const bar = new AsciiBar('#spinner #percent #bar Overall time: #overall ##blue #message');\n````\nYou can use and mix the following placeholders and modificators:\n\n| Placeholder | Description                         | Example             |\n|-------------|-------------------------------------|---------------------|\n| #bar        | The visualized progress bar         | [\u003e\u003e\u003e\u003e\u003e\u003e\u003e\u003e------]    |\n| #count      | Count of done tasks and total tasks | [12/42]             |\n| #percent    | Percentage of done tasks            | 30%                 |\n| #overall    | Estimated overall time              | 1h 12m              |\n| #elapsed    | Elapsed time                        | 1d 2h 34m           |\n| #ttf        | Estimated time to finish            | 34m 13s             |\n| #message    | Information about the current task  | Uploading dummy.txt |\n| #spinner    | A spinner                           | ⠼                   |\n| ##default   | Reset text formatting               | default text        |\n| ##green     | green text                          | \u003cspan style=\"color:green;\"\u003egreen text\u003c/span\u003e           |\n| ##blue      | blue text                           | \u003cspan style=\"color:blue;\"\u003eblue text \u003c/span\u003e           |\n| ##red       | red text                            | \u003cspan style=\"color:red;\"\u003ered text  \u003c/span\u003e           |\n| ##yellow    | yellow text                         | \u003cspan style=\"color:yellow;\"\u003eyellow text  \u003c/span\u003e        |\n| ##bright    | bright text                         | \u003cspan style=\"color:lightblue;\"\u003ebright blue text \u003c/span\u003e    |\n| ##dim       | dimmed text                         | \u003cspan style=\"color:darkgreen;\"\u003edimmed green text  \u003c/span\u003e |\n\n\n### Options\n\nYou can also use a configuration object in the constructor:\n\n````javascript\n    const bar = new AsciiBar({\n        undoneSymbol: \"-\",\n        doneSymbol: \"\u003e\",\n        width: 20,\n        formatString: '#percent #bar',\n        total: 100,\n        enableSpinner: false,\n        lastUpdateForTiming: false,\n        autoStop : true,\n        print: true,\n        start: 0,\n        startDate: new Date().getTime(),\n        stream: process.stdout,\n        hideCursor: false,\n    });\n````\n\nFor more detailed explanation off all these options have a look at the [AsciiBar.d.ts](dist/AsciiBar.d.ts#L91)\n\n### Spinner\n\n![Screenshot - made with termToSvg](https://raw.githubusercontent.com/superjojo140/ascii-bar/main/example/spinner.svg)\n\n#### Use a spinner\n\nTo use a spinner simply set the `enableSpinner` option to `true`.\nAlso use the `#spinner` placeholder in your template string.\n\nMinimal example:\n\n````javascript\n    const bar = new AsciiBar({\n        formatString: '#spinner #percent #bar',\n        enableSpinner: true\n    });\n````\n\n#### Modify spinner\n\nYou can also set a [custom spinner](dist/AsciiBar.d.ts#L164)   \nFor more spinner inspiration see [cli-spinners](https://www.npmjs.com/package/cli-spinners)\n\n````javascript\n    bar.spinner = {\n        interval: 100,\n        frames: [\"⠋\", \"⠙\", \"⠹\", \"⠸\", \"⠼\", \"⠴\", \"⠦\", \"⠧\", \"⠇\", \"⠏\"]\n    }   \n````\n\n## API Methods and properties\n\n### Methods\n\n````javascript\n    /**\n     * update the progress. This will trigger re-rendering the progressbar\n     * @param current - the new absolute progress value\n     * @param message - [optional] update the message displayed at the #message placeholder\n     */\n    bar.update(current: number, message?: string)\n\n     /**\n     * Creates the progressbar string with all configured settings\n     * @returns a string representating the progressbar\n     */\n    bar.renderLine(): string \n\n    /**\n     * Stop the progressbar\n     * This will stop the spinner and change it's symbol to a checkmark (if not disabled)\n     * Message will be changed to a string describing the elapsed time (if not disabled)\n     * This function will be triggered automatically if the progressbar reaches 100% (if not disabled)\n     * @param withInfo - wether to auto-update the progressbar's spinner and message after stopping\n     */\n    bar.stop(withInfo = true) \n````\n\n\n### Properties\n\nAll of this properties can be changed (even while the progressbar is running).\n\nE.g. to set a new message text do:\n\n````javascript\n    bar.message = \"SomeNewText\";\n````\n\n````javascript\n    /**\n     * Format of the displayed progressbar\n     */\n    public formatString = '#percent #bar';\n\n    /**\n    * Number of steps to finish progress\n    */\n    public total = 100;\n\n    /**\n     * Startdate to calculate elapsed time (in milliseconds)\n     */\n    public startDate = new Date().getTime();\n\n    /**\n     * Which time span to use for timing calculation - If you are unsure always use false here!\n     */\n    public lastUpdateForTiming = false;\n\n    /**\n     * Width of the progress bar (only the #bar part)\n     */\n    public width = 20;\n\n    /**\n    * Symbol for the done progress in the #bar part\n    */\n    public doneSymbol = \"\u003e\";\n\n    /**\n    * Symbol for the undone progress in the #bar part\n    */\n    public undoneSymbol = \"-\";\n\n    /**\n    * Wether to print to configured stream or not\n    */\n    public print = true;\n\n    /**\n     * A spinner object describing how the spinner looks like\n     * Change this for another spinner\n     */\n    public spinner = defaultSpinner;\n\n    /**\n     * The message displayed at the #message placeholder\n     */\n    public message = \"\";\n\n    /**\n    * wether to call progressbar's stop() function automatically if the progress reaches 100%\n    */\n    public autoStop = true;\n\n      /**\n     * wether to hide the terminal's cursor while displaying the progress bar\n     * cursor will be re-enabled by the bar.stop() function\n     * @default false\n     */\n    hideCursor?: boolean;\n````\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsuperjojo140%2Fascii-bar","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsuperjojo140%2Fascii-bar","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsuperjojo140%2Fascii-bar/lists"}