{"id":20556471,"url":"https://github.com/author/table","last_synced_at":"2025-07-05T06:06:49.760Z","repository":{"id":57099834,"uuid":"257452001","full_name":"author/table","owner":"author","description":"A lightweight, cross-runtime text formatting library for producing text-based tables. Designed for use with CLI and text-based applications.","archived":false,"fork":false,"pushed_at":"2021-08-22T21:21:40.000Z","size":79,"stargazers_count":5,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-06-16T17:06:13.754Z","etag":null,"topics":["ascii","cli","format","formatter","formatting","table","text"],"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/author.png","metadata":{"files":{"readme":"README.md","changelog":null,"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":"2020-04-21T01:47:37.000Z","updated_at":"2023-12-04T08:14:17.000Z","dependencies_parsed_at":"2022-08-22T23:10:40.004Z","dependency_job_id":null,"html_url":"https://github.com/author/table","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":"author/template-cross-runtime","purl":"pkg:github/author/table","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/author%2Ftable","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/author%2Ftable/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/author%2Ftable/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/author%2Ftable/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/author","download_url":"https://codeload.github.com/author/table/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/author%2Ftable/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263692892,"owners_count":23496943,"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","format","formatter","formatting","table","text"],"created_at":"2024-11-16T03:28:06.947Z","updated_at":"2025-07-05T06:06:49.693Z","avatar_url":"https://github.com/author.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @author.io/table ![Version](https://img.shields.io/github/v/tag/author/table?label=Latest\u0026style=for-the-badge)\n\n![Test and Build](https://github.com/author/table/workflows/Publish/badge.svg) using the  [cross-runtime template](https://github.com/author/template-cross-runtime).\n\nThe table module generates nicely formatted/align text (UTF8) based tables. It was designed for use with [@author.io/shell](https://github.com/author/shell), but it is a generic library that can be used in any type of text application. It works across runtimes (Node.js, browsers), contains unit tests and source maps, and is available via popular CDN's. It has no dependencies and remaining lightweight is a key priority of this library (there are many other text table formatting libraries that do everything under the sun).\n\n**Example:**\n\n```javascript\nconst rows = [\n  ['Column 1', 'Column 2', 'Column 3'],\n  ['test', '[-o, -opt]', 'This is an example, using a run-on sentence that should break onto a separate line or multiple lines depending on the table with specified.'],\n  ['cmd', '', 'Another command description.']\n]\n\nconst table = new Table(rows)\n\nconsole.log(table.output)\n```\n\n**The default output:**\n\n```sh\nColumn 1                  Column 2                  Column 3\ntest                      [-o, -opt]                This is an example, using a\n                                                    run-on sentence that should\n                                                    break onto a separate line\n                                                    or multiple lines depending\n                                                    on the table with specified.\ncmd                                                 Another command description.\n```\n\n## Installation \u0026 Usage\n\n### For Modern Node (ES Modules)\n\n`npm install @author.io/table`\n\nPlease note, you'll need a verison of Node that supports ES Modules. In Node 12, this feature is behind the `--experimental-modules` flag. It is available in Node 13+ without a flag, but your `package.json` file must have the `\"type\": \"module\"` attribute. This feature will be generally available in Node 14.0.0 (release date April 21, 2020).\n\n### For Browsers\n\n**CDN**\n\n```javascript\nimport Table from 'https://cdn.jsdelivr.net/npm/@author.io/table/index.min.js'\n```\n\nAlso available from [unpkg](https://unpkg.com/@author.io/browser-table).\n\n### Debugging\n\nEach distribution has a corresponding `-debug` version that should be installed _alongside_ the main module (the debugging is an add-on module). For example, `npm install @author.io/table-debug --save-dev` would install the debugging code.\n\n---\n\n## Default configuration\n\nEach of these are modifiable using methods and/or configuration parameters (detailed below).\n\n1. _80 characters wide._\n1. _Equally distributed column widths._\n1. _Left aligned columns._\n1. _No cellspacing._\n1. _No table margins._\n1. _Long content is wrapped._\n\n**All _empty columns are stripped_. Here's why:**\n\nThere is no need for an empty column.\n\n**_But... I want an empty column!_**\nBlank columns usually have a header. This is different from an empty column, which has NO content. For example:\n\n```sh\nColumn 1                  Column 2                  Column 3\ntest                                                This is an example...\ntest2                                               This is an example...\ntest3                                               This is an example...\n```\n\n`Column 2` is _blank_. If there were no header, it would be considered \"empty\".\n\n**_But, but... I want to use an empty column as a spacer!_**\nUse cellspacing to create space separation between columns.\n\n**_But, but, BUT... I want to use an empty column to add space to a SPECIFIC column!_**\nTo add space before/after a specific column, pad the content.\n\n## Customizing Output\n\nThe table class accepts several configuration options.\n\n```javascript\nnew Table(rows, columnAlignment, columnWidths, tableWidth, tableMargins)\n```\n\n### Rows (required)\n\nThis is an array of arrays. The main array contains rows. Each \"subarray\" contains the column data.\n\n_Example:_\n```javascript\n[\n  ['Column 1', 'Column 2', 'Column 3'], // Row 1\n  ['Column 1', 'Column 2', 'Column 3'], // Row 2\n  ['Column 1', 'Column 2', 'Column 3']  // Row 3\n]\n```\n\n### Column Alignment\n\nThis is an array of characters, where each character represents alignment of a column.\n\n_Example:_\n\n```javascript\n[\n  'l', // Left align column 1\n  'c', // Center align column 2\n  'r'  // Right align column 3\n]\n```\n\n### Column Widths\n\nThis is an array of numbers or strings. Each value represents the width of a column. A number represents how many characters wide the column will be. A string can represent a percentage, such as `50%` to represent half the width of the total table. It's possible to mix these, but isn't thoroughly tested. As a result, it's recommended to use one or other instead of mixing percentages with explicit numeric widths.\n\n_Percentage Example: (Assume an 80 character-wide table)_\n\n```javascript\n[\n  '20%', // Column 1 will be 16 characters wide\n  '20%', // Column 2 will be 16 characters wide\n  '60%'  // Column 3 will be 48 characters wide\n]\n```\n\n_Numeric Example: (Assume an 80 character-wide table)_\n\n```javascript\n[\n  16, // Column 1 will be 16 characters wide\n  16, // Column 2 will be 16 characters wide\n  48  // Column 3 will be 48 characters wide\n]\n```\n\n### Table Width\n\nThis is the maximum width of the table, in characters. Default is 80.\n\n_Examples:_\n```javascript\nconst table = new Table(rows, null, null, 80, null)\n```\n\n### Table Margins\n\nIt is possible to add spacing around the table.\n\nThe syntax is:\n\n```javascript\n[\u003cleft\u003e[, \u003cright\u003e][, \u003ctop\u003e][, \u003cbottom\u003e]]\n```\n\nEverything is available. All unspecified values default to `0`.\n\n_Example:_\n```javascript\n[\n  2, // Left margin will be 2 empty spaces\n  2, // Right margin will be 2 empty spaces\n  1, // Top margin will be 1 empty spaces\n  1  // Bottom margin will be 1 empty spaces\n]\n```\n\nThis is represented as you would expect (borders for illustration purposes only):\n\n```sh\n--------------------------\n|           Top          |\n|  --------------------  |\n|L |                  |R |\n|e |       Table      |i |\n|f |  (76 chars wide) |g |\n|t |                  |h |\n|  |                  |t |\n|  --------------------  |\n|          Bottom        |\n--------------------------\n```\n\n## Advanced Formatting Options\n\nIn addition to basic arguments, there are several other settings/methods to help customize the output.\n\n### Cellspacing\n\nCellspacing is a number of characters applied after every column except the last one. By default, there is no cellspacing (i.e. `0`).\n\n**WARNING: This will expand the width of your table!** (Calculate accordingly)\n\n_Example:_\n\n```javascript\nconst rows = [\n  ['a', 'b'],\n  ['c', 'd']\n]\n\nconst table = new Table(rows, null, null, 4)\ntable.cellspacing = 2\n```\n\n_Output:_\n```sh\n# Spaces represented by underscores for illustration purposes\na___b_\nc___d_\n```\n\nThe cellspacing is then injected at the end of each column (except the last).\n\nIf cellspacing had _not_ been defined, the output would have looked like:\n\n```sh\na_b_\nc_d_\n```\n\nThe output above is 4 characters wide. There would be a space after `b` and `d` since the table is 4 characters wide and left aligned (each column is 2 characters wide, but with no cellspacing).\n\n### Custom Fill Character\n\nIn most cases, using a space is the best custom fill character. However; it is possible to modify this using the `fill` property. We don't really see many use cases for this (other than leader lines), but it's there if you need it.\n\n_Example:_\n\n```javascript\nconst rows = [\n  ['a', 'b'],\n  ['c', 'd']\n]\n\nconst table = new Table(rows, null, null, 10)\n\ntable.fill = '*'\n\nconsole.log(table.output)\n```\n\n_Output:_\n```sh\na****b****\nc****d****\n```\n\n### Wrapping \u0026 Truncating Long Text\n\nBy default, long text is wrapped in a column. It is possible to truncate one or more columns instead of wrapping text.\n\n_1. To truncate all columns:_\n\n```javascript\nconst table = new Table(rows)\ntable.truncate()\n```\n\n_2. To truncate specific columns: (uses a 1-based column index)_\n\n```javascript\nconst table = new Table(rows)\ntable.truncate(2, 4) // Truncate column #2 and column #4\n```\n\n_3. Clear truncation:_\n\n```javascript\nconst table = new Table(rows)\ntable.truncate(0) // Anything 0 or less\n```\n\n**NOTICE** there is no way to modify truncation properties of a specific column. If you need to \"modify\", clear truncation and reset (i.e. use example 3, then example 2).\n\n## Additional Properties\n\nThe class has 4 read-only properties:\n\n1. `columns` - the raw column map\n1. `columnCount` - The number of columns.\n1. `rows` - The raw row object, updated with appropriate formatting.\n1. `rowCount` - the number of rows.\n\n```javascript\nconst table = new Table(rows)\n\nconsole.log(table.rowCount, table.columnCount)\n```\n\n## Miscellaneous Notes\n\nThis class replaces tab characters with two spaces. This is an opinionated decision to prevent inconsistencies in display.\n\nIf you disagree with this opinion the workaround is to extend the class:\n\n```javascript\nclass MyTable extends Table {\n  constructor () {\n    super()\n\n    this.#tabWidth = 4\n  }\n}\n\nconst table = new MyTable(rows)\n```\n\n## Credits\n\nCreated by [Corey Butler](https://github.com/coreybutler) for [Author.io](https://author.io).\n\n**Sponsors (as of 2021)**\n\n\u003ctable cellpadding=\"10\" cellspacing=\"0\" border=\"0\"\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ca href=\"https://metadoc.io\"\u003e\u003cimg src=\"https://github.com/coreybutler/staticassets/raw/master/sponsors/metadoclogobig.png\" width=\"200px\"/\u003e\u003c/a\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003ca href=\"https://butlerlogic.com\"\u003e\u003cimg src=\"https://github.com/coreybutler/staticassets/raw/master/sponsors/butlerlogic_logo.png\" width=\"200px\"/\u003e\u003c/a\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fauthor%2Ftable","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fauthor%2Ftable","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fauthor%2Ftable/lists"}