Skip to main content

​
Your First Table

This guide will walk you through creating a simple, formatted CLI table using Tabular. We’ll build a table displaying countries and their capitals.
1

Include the headers

Start by including the necessary Tabular headers in your C++ file:
#include "tabular/table.h"
#include "tabular/render.h"
  • table.h: Provides the Table class for creating tables
  • render.h: Provides the render() function for cross-platform output
2

Create a Table object

In your main() function, create a Table instance:
int main()
{
  using namespace tabular;
  Table table;
The Table class is the core component for building your CLI table.
3

Add rows to the table

Use the addRow() method to populate your table with data:
  table.addRow({"Countries Capitals"})
      .addRow({"United States", "Washington"})
      .addRow({"Brazil", "Brasilia"})
      .addRow({"France", "Paris"})
      .addRow({"Japan", "Tokyo"})
      .addRow({"India", "New Delhi"});
  • Each addRow() call takes a vector of strings
  • The method returns a reference to the table, allowing method chaining
  • Rows can have different numbers of columns (flexible tables)
4

Render the table

Convert the table to a string and render it to the console:
  render(table.str() + '\n', stdout);
  return 0;
}
  • table.str(): Converts the table to its string representation
  • render(): Ensures cross-platform rendering, especially for Unicode characters

​
Complete Example

Here’s the complete code from the example: 
#include "tabular/table.h"
#include "tabular/render.h"

int main()
{
  using namespace tabular;
  Table table;

  table.addRow({"Countries Capitals"})
      .addRow({"United States", "Washington"})
      .addRow({"Brazil", "Brasilia"})
      .addRow({"France", "Paris"})
      .addRow({"Japan", "Tokyo"})
      .addRow({"India", "New Delhi"});

  render(table.str() + '\n', stdout);
  return 0;
}

​
Compile and Run

Compile your program with C++11 support: 
g++ -std=c++11 basic.cpp -o basic
./basic
Or with CMake: 
mkdir build && cd build
cmake ..
make
./basic

​
Expected Output

Your program will output a nicely formatted table: 
┌──────────────────────────────────────────────────┐
│Countries Capitals                                │
├────────────────────────────┬─────────────────────┤
│United States               │Washington           │
├────────────────────────────┼─────────────────────┤
│Brazil                      │Brasilia             │
├────────────────────────────┼─────────────────────┤
│France                      │Paris                │
├────────────────────────────┼─────────────────────┤
│Japan                       │Tokyo                │
├────────────────────────────┼─────────────────────┤
│India                       │New Delhi            │
└────────────────────────────┴─────────────────────┘
The default table width is 50 characters. You can customize this and many other aspects of your table.

​
Alternative Output Method

For simple ASCII tables, you can also use std::cout directly: 
std::cout << table.str() << '\n';
However, for tables containing multibyte characters (Unicode, CJK characters, etc.), it’s recommended to use the render() function for proper cross-platform display.

​
Next Steps

Now that you’ve created your first table, explore more features:

Width System

Learn how to configure table width, alignment, and padding

Styling

Add colors, text attributes, and visual effects to your tables

Borders

Customize table borders with pre-defined templates or create your own

Examples

Explore more examples and advanced features

​
Tips

  • Method Chaining: addRow() returns a reference to the table, allowing you to chain multiple calls
  • Flexible Columns: Rows can have different numbers of columns - Tabular handles this automatically
  • Default Width: Tables default to 50 characters wide, but this is easily customizable with table.config().width()
  • Unicode Support: Always use render() for tables with Unicode characters to ensure proper display

Build docs developers (and LLMs) love

Get started for freeTalk to us