org-table-wrap manual
Table of contents
Overview
Org mode tables are plain-text constructs: every cell in a row must fit on a single line. When a table has many columns or columns with long content, the table extends beyond the window width and the user must scroll horizontally to see it. This is disruptive, especially in documents with mixed prose and tabular data.
org-table-wrap.el solves this problem by providing visual word-wrapping for Org tables that overflow the window. It uses overlays with the invisible property and before-string to replace an overflowing table with a wrapped rendering that uses Unicode box-drawing characters (or ASCII equivalents). The buffer text is never modified: the wrapped view is purely cosmetic.
The package follows the same reveal-on-enter pattern used by org-appear: when point enters a wrapped table, the overlay is removed so you can edit the table normally. When point leaves, the overlay is re-applied. Window resize events trigger automatic re-processing of all tables, with a short idle debounce to avoid unnecessary work during rapid resizing.
The rendering pipeline works in two phases. First, column widths are allocated proportionally based on each column’s natural (max-content) width, respecting a configurable minimum (org-table-wrap-min-column-width). Second, the overlay is applied and measured pixel-accurately; if the rendered table still overflows (due to variable-width fonts, display scaling, or face remapping), columns are shrunk iteratively until the table fits.
org-table-wrap.el requires Emacs 29.1 or later and Org 9.6 or later.
The development repository is on GitHub.
User options
Visual appearance
The user option org-table-wrap-use-unicode controls whether the wrapped table uses Unicode box-drawing characters or ASCII equivalents. When non-nil (the default), borders are drawn with characters such as │, ─, ┌, ┘, ┼, producing a clean, modern look. When nil, the package falls back to |, -, and +, which may be preferable in terminals with limited Unicode support or when copy-pasting table output to plain-text contexts.
The user option org-table-wrap-padding is an integer specifying the number of spaces between the cell content and the column border on each side. The default value is 1, which gives cells a comfortable amount of breathing room. Setting it to 0 produces a more compact table, while higher values increase readability at the cost of horizontal space. Since padding is applied on both sides of each cell in every column, increasing this value by 1 consumes 2 * ncols additional characters of width across the table.
Column sizing
The user option org-table-wrap-min-column-width sets the minimum character width for any column in a wrapped table. The default value is 5. This prevents columns from being squeezed to an unreadably narrow width when the table has many columns competing for limited horizontal space. If you frequently work with tables that have many short-content columns (such as boolean flags or single-digit numbers), you might lower this to 3. Conversely, if your tables contain mostly prose, raising this value ensures that even the narrowest column can display a meaningful fragment of text.
The user option org-table-wrap-width-fraction is a float that determines what fraction of the window width the wrapped table is allowed to occupy. The default value is 0.75, which is deliberately conservative: it provides a safety margin that compensates for font rendering differences, display scaling, and the prefix overhead introduced by org-indent-mode. If the wrapped table appears too narrow for your setup, increase this value toward 1.0. A value of 1.0 uses the full window width, which works well with monospaced fonts and no indentation mode, but may cause slight overflow with proportional fonts or high DPI scaling.
The width fraction works in concert with the pixel-accurate fitting phase described in the Overview: even if the character-based allocation fits within the fraction, the pixel measurement may trigger further shrinking. The fraction therefore acts as a first-pass target, not a hard guarantee.
Commands
Enabling the mode
The command org-table-wrap-mode is a buffer-local minor mode that activates visual word-wrapping for Org tables in the current buffer. When enabled, all tables in the buffer are scanned: those wider than the window receive an overlay that displays the wrapped rendering. The mode lighter is OTW.
Invoke it interactively with M-x org-table-wrap-mode, or enable it from your init file for all Org buffers:
(add-hook 'org-mode-hook #'org-table-wrap-mode)
While the mode is active, a post-command-hook tracks point movement. When point enters a wrapped table, the overlay is removed so you can edit the underlying Org table normally. When point leaves, the overlay is re-applied. This reveal-on-enter behavior is similar to what org-appear does for emphasis markers and links.
A window-size-change-functions hook ensures that all wrapped tables are re-processed when the window is resized. Resize events are debounced with a 0.2-second idle timer to avoid redundant work during rapid resizing (such as dragging a window edge).
If the buffer is not yet displayed in any window when the mode is enabled (for example, when a file is opened in the background), processing is deferred via window-configuration-change-hook until the buffer becomes visible. This avoids errors from trying to measure pixel widths without a live window.
When the mode is disabled, all overlays are removed, the invisibility spec is cleaned up, and the hooks are removed. The global resize hook is only removed when no other buffer in the session uses org-table-wrap-mode.
The command global-org-table-wrap-mode is a globalized minor mode that automatically enables org-table-wrap-mode in every Org buffer. This is the most convenient way to use the package:
(global-org-table-wrap-mode 1)