TextTable

Display tabular data with flexible layouts, borders, and text wrapping

Overview

TextTableRenderable renders tabular data with customizable borders, wrapping modes, and column sizing strategies. It supports text selection across cells, multiple border styles, and handles complex content including styled text and Unicode characters.

Basic Usage

import { TextTableRenderable, createCliRenderer } from '@opentui/core'

const renderer = await createCliRenderer()

const table = new TextTableRenderable(renderer, {
  content: [
    [[{ __isChunk: true, text: 'Name' }], [{ __isChunk: true, text: 'Status' }]],
    [[{ __isChunk: true, text: 'API' }], [{ __isChunk: true, text: 'OK' }]],
    [[{ __isChunk: true, text: 'Worker' }], [{ __isChunk: true, text: 'ERROR' }]],
  ],
  wrapMode: 'word',
  borderStyle: 'single',
})

renderer.root.add(table)

With Styled Content

import { TextTableRenderable, bold, fg } from '@opentui/core'

const table = new TextTableRenderable(renderer, {
  content: [
    [[bold('Service')], [bold('Status')], [bold('Latency')]],
    [
      [{ __isChunk: true, text: 'api' }],
      [fg('#00d4aa')('OK')],
      [{ __isChunk: true, text: '28ms' }],
    ],
    [
      [{ __isChunk: true, text: 'worker' }],
      [fg('#b8a0ff')('DEGRADED')],
      [{ __isChunk: true, text: '124ms' }],
    ],
    [
      [{ __isChunk: true, text: 'billing' }],
      [fg('#ffffff')('ERROR')],
      [{ __isChunk: true, text: 'timeout' }],
    ],
  ],
  borderStyle: 'rounded',
  borderColor: '#2a2a2a',
  fg: '#f0f0f0',
  cellPadding: 1,
})

Full Width Table

const table = new TextTableRenderable(renderer, {
  content: [
    [[{ __isChunk: true, text: 'Region' }], [{ __isChunk: true, text: 'Requests' }]],
    [[{ __isChunk: true, text: 'us-east-1' }], [{ __isChunk: true, text: '1.2M' }]],
    [[{ __isChunk: true, text: 'eu-west-1' }], [{ __isChunk: true, text: '890K' }]],
  ],
  width: '100%',
  columnWidthMode: 'full', // Expand columns to fill available width
  wrapMode: 'word',
})

Text Wrapping

// Long content that wraps within cells
const table = new TextTableRenderable(renderer, {
  content: [
    [
      [{ __isChunk: true, text: 'Task' }],
      [{ __isChunk: true, text: 'Description' }],
    ],
    [
      [{ __isChunk: true, text: 'Migration' }],
      [{ __isChunk: true, text: 'Migrate all production databases to the new infrastructure with zero downtime and full data validation' }],
    ],
  ],
  wrapMode: 'word', // 'none' | 'word' | 'char'
  columnFitter: 'balanced', // Better distribution for wrapped content
})

Border Styles

// Different border configurations
const doubleBorder = new TextTableRenderable(renderer, {
  content: data,
  borderStyle: 'double',
  border: true,
  outerBorder: true,
})

const innerOnly = new TextTableRenderable(renderer, {
  content: data,
  border: true,
  outerBorder: false, // Only show borders between cells
})

const noBorders = new TextTableRenderable(renderer, {
  content: data,
  showBorders: false, // Hide all borders while preserving layout
})

Unicode and CJK Support

const unicodeTable = new TextTableRenderable(renderer, {
  content: [
    [[{ __isChunk: true, text: 'Locale' }], [{ __isChunk: true, text: 'Sample' }]],
    [[{ __isChunk: true, text: 'ja-JP' }], [{ __isChunk: true, text: '東京の夜景と絵文字 🌃✨' }]],
    [[{ __isChunk: true, text: 'zh-CN' }], [{ __isChunk: true, text: '你好世界，布局检查中 🚀' }]],
    [[{ __isChunk: true, text: 'ko-KR' }], [{ __isChunk: true, text: '한글과 이모지 조합 테스트 😄' }]],
  ],
  wrapMode: 'char', // Better for CJK text
})

Props

content · TextTableContent · default: "[]"

Table data as a 2D array of cell content. Each cell contains TextChunk[] or null/undefined.

type TextTableContent = TextTableCellContent[][]
type TextTableCellContent = TextChunk[] | null | undefined

wrapMode · 'none' | 'char' | 'word' · default: "'word'"

Text wrapping behavior within cells:

• 'none': No wrapping, content may overflow
• 'word': Wrap at word boundaries
• 'char': Wrap at any character (better for CJK)

columnWidthMode · 'content' | 'full' · default: "'full'"

Column sizing strategy:

• 'content': Columns sized to fit content
• 'full': Columns expand to fill available width

columnFitter · 'proportional' | 'balanced' · default: "'proportional'"

Algorithm for shrinking columns when content exceeds available width:

• 'proportional': Shrink proportionally to intrinsic width
• 'balanced': More even distribution using sqrt-based weighting

cellPadding · number · default: "0"

Padding around cell content (applied to all sides). Minimum value is 0.

showBorders · boolean · default: "true"

Whether to draw borders. When false, borders are hidden but layout remains the same.

border · boolean · default: "true"

Whether to show inner borders between cells.

outerBorder · boolean · default: "true"

Whether to show the outer border around the entire table.

borderStyle · BorderStyle · default: "'single'"

Border drawing style: 'single' | 'rounded' | 'double' | 'heavy'

borderColor · ColorInput · default: "'#FFFFFF'"

Color of the border lines. Accepts hex colors, RGB objects, or color names.

borderBackgroundColor · ColorInput · default: "'transparent'"

Background color behind borders.

backgroundColor · ColorInput · default: "'transparent'"

Background color for the entire table.

fg · ColorInput · default: "'#FFFFFF'"

Default text color for cell content.

bg · ColorInput · default: "'transparent'"

Default background color for cell content.

attributes · number · default: "0"

Default text attributes (bold, italic, etc.) as a bitmask.

selectable · boolean · default: "true"

Whether table content can be selected with mouse drag.

selectionBg · ColorInput

Background color for selected text.

selectionFg · ColorInput

Foreground color for selected text.

Methods

content

Get or set the table content.

table.content = newData
const currentData = table.content

wrapMode

Get or set the text wrapping mode.

table.wrapMode = 'char'

columnWidthMode

Get or set the column width mode.

table.columnWidthMode = 'content'

columnFitter

Get or set the column fitting algorithm.

table.columnFitter = 'balanced'

cellPadding

Get or set the cell padding.

table.cellPadding = 1

showBorders

Get or set border visibility.

table.showBorders = false

border

Get or set inner border display.

table.border = false

outerBorder

Get or set outer border display.

table.outerBorder = true

borderStyle

Get or set the border style.

table.borderStyle = 'double'

borderColor

Get or set the border color.

table.borderColor = '#2a2a2a'

getSelectedText()

Get the currently selected text from the table. Returns tab-separated columns and newline-separated rows.

const selected = table.getSelectedText()
// Example output: "api\tOK\t28ms\nworker\tDEGRADED\t124ms"

Selection Support

TextTableRenderable supports three selection modes:

• single-cell: Selection within one cell
• column-locked: Selection across rows in the same column
• grid: Free selection across any cells

renderer.on('selection', (selection) => {
  const selectedText = table.getSelectedText()
  console.log('Selected:', selectedText)
})

// Clear selection
renderer.clearSelection()

Common Patterns

Dynamic Data Updates

function updateTableData(newData: TextTableContent) {
  table.content = newData
  // Table automatically recalculates layout and re-renders
}

setInterval(() => {
  updateTableData(fetchLatestData())
}, 1000)

Responsive Width

const table = new TextTableRenderable(renderer, {
  content: data,
  width: '100%', // Fill parent width
  columnWidthMode: 'full',
  wrapMode: 'word',
  flexGrow: 1, // Grow with parent
})

Status Dashboard

const statusTable = new TextTableRenderable(renderer, {
  content: [
    [[bold('Service')], [bold('Status')], [bold('Uptime')]],
    ...services.map(s => [
      [{ __isChunk: true, text: s.name }],
      [fg(s.healthy ? '#00ff00' : '#ff0000')(s.status)],
      [{ __isChunk: true, text: s.uptime }],
    ]),
  ],
  borderStyle: 'rounded',
  cellPadding: 1,
  width: '100%',
})

Performance Notes

• Tables efficiently handle cell content changes by only rebuilding modified cells
• Layout computation is cached and only recalculated when dimensions or content change
• Large tables with wrapping enabled may require more computation for layout
• Use columnWidthMode: 'content' for better performance with fixed-width content

Related Components

• Box - Container for tables
• ScrollBox - Scrollable container for large tables
• Text - For styled text content in cells