Format - Tabulate

Overview

The Format class provides a comprehensive set of methods for customizing the appearance of tables, rows, columns, and cells. All format methods return a reference to the Format object, enabling method chaining.

Dimensions

width

Format& width(size_t value)

Sets the width of the element.

value

size_t

The width in characters.

Example:

table[0][0].format().width(20);

height

Format& height(size_t value)

Sets the height of the element.

value

size_t

The height in rows.

Padding

padding

Format& padding(size_t value)

Sets padding on all sides (left, right, top, bottom).

value

size_t

The padding value to apply to all sides.

Example:

table.format().padding(2);

padding_left

Format& padding_left(size_t value)

Sets left padding.

padding_right

Format& padding_right(size_t value)

Sets right padding.

padding_top

Format& padding_top(size_t value)

Sets top padding.

padding_bottom

Format& padding_bottom(size_t value)

Sets bottom padding.

Borders

border

Format& border(const std::string& value)

Sets all border characters (left, right, top, bottom).

value

const std::string&

The character(s) to use for all borders.

Example:

table.format().border("*");

border_left / border_right / border_top / border_bottom

Format& border_left(const std::string& value)
Format& border_right(const std::string& value)
Format& border_top(const std::string& value)
Format& border_bottom(const std::string& value)

Sets individual border characters. Example:

table.format()
  .border_left("|")
  .border_right("|")
  .border_top("-")
  .border_bottom("-");

Border Visibility

Format& show_border()
Format& hide_border()
Format& show_border_top()
Format& hide_border_top()
Format& show_border_bottom()
Format& hide_border_bottom()
Format& show_border_left()
Format& hide_border_left()
Format& show_border_right()
Format& hide_border_right()

Controls which borders are displayed. Example:

table[0].format()
  .hide_border_top()
  .show_border_bottom();

show_row_separator

Format& show_row_separator()

Enables row separators between rows.

Border Colors

border_color

Format& border_color(Color value)

Sets the color for all borders.

value

Color

Color enum value: none, grey, red, green, yellow, blue, magenta, cyan, white.

Example:

table.format().border_color(Color::blue);

border_background_color

Format& border_background_color(Color value)

Sets the background color for all borders.

Individual Border Colors

Format& border_left_color(Color value)
Format& border_right_color(Color value)
Format& border_top_color(Color value)
Format& border_bottom_color(Color value)

Format& border_left_background_color(Color value)
Format& border_right_background_color(Color value)
Format& border_top_background_color(Color value)
Format& border_bottom_background_color(Color value)

Sets colors for individual borders.

Corners

corner

Format& corner(const std::string& value)

Sets all corner characters.

value

const std::string&

The character(s) to use for all corners.

Example:

table.format().corner("+");

corner_color

Format& corner_color(Color value)

Sets the color for all corners.

corner_background_color

Format& corner_background_color(Color value)

Sets the background color for all corners.

Individual Corners

Format& corner_top_left(const std::string& value)
Format& corner_top_right(const std::string& value)
Format& corner_bottom_left(const std::string& value)
Format& corner_bottom_right(const std::string& value)

Format& corner_top_left_color(Color value)
Format& corner_top_right_color(Color value)
Format& corner_bottom_left_color(Color value)
Format& corner_bottom_right_color(Color value)

Format& corner_top_left_background_color(Color value)
Format& corner_top_right_background_color(Color value)
Format& corner_bottom_left_background_color(Color value)
Format& corner_bottom_right_background_color(Color value)

Sets individual corner characters and colors.

Column Separator

column_separator

Format& column_separator(const std::string& value)

Sets the column separator character.

value

const std::string&

The character(s) to use for column separation.

column_separator_color

Format& column_separator_color(Color value)

Sets the column separator color.

column_separator_background_color

Format& column_separator_background_color(Color value)

Sets the column separator background color.

Font Styling

font_align

Format& font_align(FontAlign value)

Sets text alignment.

value

FontAlign

Alignment enum: FontAlign::left, FontAlign::center, or FontAlign::right.

Example:

table[0].format().font_align(FontAlign::center);

font_style

Format& font_style(const std::vector<FontStyle>& style)

Sets font styles. Multiple styles can be combined.

style

const std::vector<FontStyle>&

Vector of FontStyle enum values: bold, dark, italic, underline, blink, reverse, concealed, crossed.

Example:

table[0].format().font_style({FontStyle::bold, FontStyle::underline});

font_color

Format& font_color(Color value)

Sets the font color.

value

Color

Color enum value.

Example:

table[0][0].format().font_color(Color::red);

font_background_color

Format& font_background_color(Color value)

Sets the font background color.

Convenience Methods

color

Format& color(Color value)

Sets font color, border color, and corner color all at once. Example:

table.format().color(Color::blue);

background_color

Format& background_color(Color value)

Sets font background color, border background color, and corner background color all at once.

Internationalization

multi_byte_characters

Format& multi_byte_characters(bool value)

Enables or disables multi-byte character support for Unicode and international characters.

value

bool

true to enable multi-byte character support, false to disable.

Example:

table[0][0].format().multi_byte_characters(true);

locale

Format& locale(const std::string& value)

Sets the locale for text processing.

value

const std::string&

Locale string (e.g., “en_US.UTF-8”).

Trim Mode

trim_mode

Format& trim_mode(TrimMode trim_mode)

Controls whitespace trimming behavior.

trim_mode

TrimMode

Enum value: TrimMode::kNone, TrimMode::kLeft, TrimMode::kRight, or TrimMode::kBoth.

Static Methods

word_wrap

static std::string word_wrap(const std::string& str, size_t width, 
                             const std::string& locale,
                             bool is_multi_byte_character_support_enabled)

Applies word wrapping to a string.

str

const std::string&

The input string to wrap.

width

size_t

The maximum line width.

locale

const std::string&

The locale for text processing.

is_multi_byte_character_support_enabled

bool

Whether multi-byte character support is enabled.

Returns: Word-wrapped string with newline characters inserted.

split_lines

static std::vector<std::string> split_lines(const std::string& text, 
                                            const std::string& delimiter,
                                            const std::string& locale,
                                            bool is_multi_byte_character_support_enabled)

Splits text into lines based on a delimiter.

text

const std::string&

The input text to split.

delimiter

const std::string&

The delimiter string to split on.

Returns: Vector of string lines.

merge

static Format merge(Format first, Format second)

Merges two Format objects, with the first having higher precedence.

first

Format

Format with higher precedence (e.g., cell-level formatting).

second

Format

Format with lower precedence (e.g., row-level formatting).

Returns: Merged Format object.

Complete Example

#include <tabulate/table.hpp>
using namespace tabulate;

int main() {
  Table styled_table;
  
  // Add data
  styled_table.add_row({"Product", "Price", "Rating"});
  styled_table.add_row({"Laptop", "$999", "4.5"});
  styled_table.add_row({"Mouse", "$29", "4.8"});
  styled_table.add_row({"Keyboard", "$79", "4.6"});
  
  // Format header row
  styled_table[0].format()
    .font_style({FontStyle::bold, FontStyle::underline})
    .font_color(Color::yellow)
    .font_background_color(Color::blue)
    .font_align(FontAlign::center)
    .padding(1);
  
  // Format data rows
  for (size_t i = 1; i < styled_table.size(); ++i) {
    styled_table[i].format().padding_left(2).padding_right(2);
  }
  
  // Format columns
  styled_table.column(0).format()
    .width(15)
    .font_align(FontAlign::left);
  
  styled_table.column(1).format()
    .width(10)
    .font_align(FontAlign::right)
    .font_color(Color::green);
  
  styled_table.column(2).format()
    .width(10)
    .font_align(FontAlign::center);
  
  // Format entire table
  styled_table.format()
    .border_top("-")
    .border_bottom("-")
    .border_left("|")
    .border_right("|")
    .corner("+")
    .border_color(Color::cyan)
    .show_row_separator();
  
  std::cout << styled_table << std::endl;
  return 0;
}

Get Started

Core Concepts

Guides

API Reference

Advanced

Examples

​Overview

​Dimensions

​width

​height

​Padding

​padding

​padding_left

​padding_right

​padding_top

​padding_bottom

​Borders

​border

​border_left / border_right / border_top / border_bottom

​Border Visibility

​show_row_separator

​Border Colors

​border_color

​border_background_color

​Individual Border Colors

​Corners

​corner

​corner_color

​corner_background_color

​Individual Corners

​Column Separator

​column_separator

​column_separator_color

​column_separator_background_color

​Font Styling

​font_align

​font_style

​font_color

​font_background_color

​Convenience Methods

​color

​background_color

​Internationalization

​multi_byte_characters

​locale

​Trim Mode

​trim_mode

​Static Methods

​word_wrap

​split_lines

​merge

​Complete Example

Build docs developers (and LLMs) love

Overview

Dimensions

width

height

Padding

padding

padding_left

padding_right

padding_top

padding_bottom

Borders

border

border_left / border_right / border_top / border_bottom

Border Visibility

show_row_separator

Border Colors

border_color

border_background_color

Individual Border Colors

Corners

corner

corner_color

corner_background_color

Individual Corners

Column Separator

column_separator

column_separator_color

column_separator_background_color

Font Styling

font_align

font_style

font_color

font_background_color

Convenience Methods

color

background_color

Internationalization

multi_byte_characters

locale

Trim Mode

trim_mode

Static Methods

word_wrap

split_lines

merge

Complete Example