console-table
A small, dependency-light Rust library for rendering aligned console tables.
It is Unicode-aware (CJK characters count as 2 columns), supports optional per-cell truncation, ANSI foreground colors, and two border styles.
Table of contents
- Features
- Installation
- Quick start
- Before and after
- API overview
- Design notes
- Windows note
- FAQ
- License
Features
- Unicode / CJK-aware alignment — uses
unicode-widthso that Chinese, Japanese, Korean, fullwidth, and zero-width characters are measured by their real terminal display width, not bycharcount. - Two border styles —
Style::Simple(header separator only) andStyle::Boxed(full box drawing). - Per-column alignment —
Align::Left,Align::Right, orAlign::Auto(numbers right-aligned, everything else left-aligned). - Truncation — cap any data cell at
max_cell_width; overflow becomes ASCII.... Headers are never truncated. - ANSI colors — optional
header_colorandbody_colorfrom a small built-in palette. - ANSI-safe width math — existing ANSI sequences inside cell text are stripped before width is measured, so colored input does not break layout.
- Only one dependency —
unicode-width.
Installation
Add this to your Cargo.toml:
[]
= "0.1"
Quick start
use ;
Output (colors not shown):
┌──────┬─────────────────────┬──────────┐
│ # │ source │ latency │
├──────┼─────────────────────┼──────────┤
│ 1 │ rsproxy (ByteDance) │ 57 ms │
│ 2 │ tuna (Tsinghua) │ 16 ms │
│ 8 │ cqu (Chongqing) │ failed │
└──────┴─────────────────────┴──────────┘
Before and after
The same CJK data, rendered three ways. The first two use plain format! and
break or bloat on Chinese text; the third uses console-table and stays
aligned with almost no boilerplate.
The runnable version of all three is in
examples/compare.rs.
let headers = ;
let data = ;
Before — manual format!
The common first attempt. {:<20} pads by char count, so Chinese characters
(which occupy 2 terminal columns each) collapse the columns.
Output:
序号 镜像源 平均延迟 可用 serde最新版
------------------------------------------------------------
1 rsproxy (字节跳动) 57 ms 是 1.0.229
2 tuna (清华) 16 ms 是 1.0.229
8 cqu (重大) 失败 否 -
Columns drift because "镜像源" is 3 chars but 6 columns wide.
Before — manual width handling
To fix it by hand, you need your own display-width function, a fixed width table, and manual padding. It works, but it is a lot of boilerplate, and every new column means editing several places.
Output:
序号 镜像源 平均延迟 可用 serde最新版
----------------------------------------------------------------------
1 rsproxy (字节跳动) 57 ms 是 1.0.229
2 tuna (清华) 16 ms 是 1.0.229
8 cqu (重大) 失败 否 -
Aligned, but no borders, no per-column alignment, no truncation, no colors.
After — console-table
use ;
let rows = vec!;
let table = new
.style
.aligns
.header_color
.body_color;
println!;
Output:
┌──────┬────────────────────┬──────────┬──────┬─────────────┐
│ 序号 │ 镜像源 │ 平均延迟 │ 可用 │ serde最新版 │
├──────┼────────────────────┼──────────┼──────┼─────────────┤
│ 1 │ rsproxy (字节跳动) │ 57 ms │ 是 │ 1.0.229 │
│ 2 │ tuna (清华) │ 16 ms │ 是 │ 1.0.229 │
│ 8 │ cqu (重大) │ 失败 │ 否 │ - │
└──────┴────────────────────┴──────────┴──────┴─────────────┘
After — with truncation
Long values are capped at max_cell_width and end with ASCII ....
Truncation never breaks alignment.
let mut rows_with_url = rows.clone;
rows_with_url.push;
let urls = ;
for in urls.iter.enumerate
let table = new
.style
.aligns
.max_cell_width
.header_color
.body_color;
println!;
Output:
┌──────┬────────────────────┬──────────┬──────┬─────────────┬──────────────────────────────────────────┐
│ 序号 │ 镜像源 │ 平均延迟 │ 可用 │ serde最新版 │ 地址 │
├──────┼────────────────────┼──────────┼──────┼─────────────┼──────────────────────────────────────────┤
│ 1 │ rsproxy (字节跳动) │ 57 ms │ 是 │ 1.0.229 │ sparse+https://rsproxy.cn/index/ │
│ 2 │ tuna (清华) │ 16 ms │ 是 │ 1.0.229 │ sparse+https://mirrors.tuna.tsinghua.edu… │
│ 8 │ cqu (重大) │ 失败 │ 否 │ - │ sparse+https://mirrors.cqu.edu.cn/crates… │
└──────┴────────────────────┴──────────┴──────┴─────────────┴──────────────────────────────────────────┘
Summary
manual format! |
manual width fn | console-table |
|
|---|---|---|---|
| CJK-aware width | ✗ | ✓ | ✓ |
| Column widths auto-computed | ✗ | ✗ | ✓ |
| Borders | ✗ | ✗ | ✓ |
| Per-column alignment | ✗ | ✗ | ✓ |
| Truncation | ✗ | ✗ | ✓ |
| Colors | ✗ | ✗ | ✓ |
| Lines of code | ~6 | ~30 | ~10 |
API overview
Table
| Method | Description |
|---|---|
Table::new(rows) |
Create a table. The first row is treated as the header. Rows may have different lengths; missing cells are treated as empty. |
.style(Style) |
Style::Simple (default) or Style::Boxed. |
.aligns(Vec<Align>) |
Per-column alignment. Missing columns default to Align::Left. |
.max_cell_width(usize) |
Truncate data cells to at most this display width. Headers are not truncated. |
.header_color(Color) |
Foreground color for the header row. |
.body_color(Color) |
Foreground color for data rows. |
.render() -> String |
Render the table. Every line ends with \n. |
Style
| Variant | Description |
|---|---|
Simple |
Header row, a single separator, then data rows. |
Boxed |
Full box drawing with top, header separator, row separators, and bottom border. |
Align
| Variant | Description |
|---|---|
Left |
Left align. |
Right |
Right align. |
Auto |
Right align if the first whitespace-separated token parses as f64, otherwise left align. |
Color
16 ANSI foreground colors:
Black,Red,Green,Yellow,Blue,Magenta,Cyan,WhiteBrightBlack,BrightRed,BrightGreen,BrightYellow,BrightBlue,BrightMagenta,BrightCyan,BrightWhite
Free functions
| Function | Description |
|---|---|
render_table(rows, style) |
Convenience: Table::new(rows).style(style).render(). |
display_width(&str) -> usize |
Terminal display width, ignoring ANSI sequences. |
truncate_visible(&str, usize) -> String |
Truncate to a display width, appending ASCII .... |
strip_ansi(&str) -> String |
Remove CSI-style ANSI escape sequences. |
pad_right_with_spaces(&str, usize) |
Pad on the right by display width. |
pad_left_with_spaces(&str, usize) |
Pad on the left by display width. |
is_numeric_like(&str) -> bool |
Heuristic used by Align::Auto. |
Design notes
- Widths are measured, not assumed. Every column is
max(display_width of all cells in that column, including the header) + 2, where+2reserves one space of padding on each side. ...instead of…. The single-character ellipsis…(U+2026) renders as 1 or 2 columns depending on the terminal and font, which breaks alignment. The ASCII...is always exactly 3 columns.- Colors are applied at render time. Width computation strips ANSI sequences, so colored cells never widen a column.
- Existing ANSI in cell text is stripped. If a cell already contains color
codes, they are removed and replaced by
body_color(or no color). Do not mix per-cell colors withbody_color. - Every rendered line has equal display width. This includes the header, separators, and data rows, so the table stays rectangular even when the terminal renders wide characters at 2 columns.
Windows note
Older cmd.exe consoles may not interpret ANSI escape sequences. Use
Windows Terminal or enable virtual terminal
processing in the console.
When redirecting output to a file, prefer disabling colors yourself:
use IsTerminal;
let table = new;
let table = if stdout.is_terminal else ;
This keeps the redirected file free of \x1b[...m sequences.
FAQ
Why does my CJK table look misaligned in some terminals?
Some terminals and fonts render … (U+2026) as 2 columns, and a few render it
as 1. This library uses ASCII ... for truncation so the width is always 3.
If you still see misalignment, check that your terminal uses a font where
CJK characters are exactly twice the width of ASCII characters.
Can I color individual cells?
Not directly. body_color applies to the whole data row, and any ANSI codes
inside a cell are stripped before rendering. If you need per-cell colors,
render the row yourself or use a lower-level API.
Why is max_cell_width applied to data cells only?
Headers are typically short labels, and truncating them can hide useful
information. If you need header truncation, apply truncate_visible to the
header string before passing it to Table::new.
Does the library write to stdout?
No. render() returns a String. Printing is up to the caller.
License
Licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)
at your option.
Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.