The Table Editor
Plain-text tables are usually painful: every edit misaligns the columns, and fixing them by hand takes longer than the edit itself. Org removes that cost. You type rough rows separated by vertical bars, press TAB, and Org aligns the whole table, widens columns, extends separator lines and moves you to the next field. The file still contains nothing but text, so the table survives version control, diffs and any other editor.
This chapter covers the editor: how a table is written, how to create, navigate and restructure it, how to control column width and alignment, and how to group columns for export. It ends with Orgtbl mode, which brings the same editor to buffers that are not Org files. Formulas and plotting build on all of this and have their own chapter, The Spreadsheet and Plotting.
What makes a table
A table in Org is a group of consecutive lines whose first non-blank character is |. The vertical bar also separates the columns. Each cell between two bars is a field.
A line that starts with |- is a horizontal rule (Org calls it an hline); it separates groups of rows. Rows above the first hline are header rows.
Figure 6.1: A table is ordinary text, and each part (header, hlines, cookie row, formulas) is recognized from the first characters of its line.
The figure shows every part you will meet in this chapter and the next:
| Part | How Org recognizes it | Purpose |
|---|---|---|
#+NAME: line | A keyword directly above the table | Lets links and formulas in other tables refer to this table. |
| Header rows | Rows above the first hline | Column titles; exported as table headers and left alone by column formulas. |
| Hline | A line starting with |- | Separates header from body, or groups of rows. |
| Cookie row | A row with only <N>, <l>, <c>, <r> or column-group markers | Display width and alignment; removed on export. |
| Field | Text between two bars | One value. Leading and trailing spaces are not part of the value. |
#+TBLFM: line | A keyword directly below the table | The table’s formulas (see The Spreadsheet and Plotting). |
The indentation of the first line sets the indentation of the whole table, so a table can sit inside a list item. A table ends at the first line that does not start with |.
Creating a table
You do not need to draw a table. Type the header with bars, start a separator line, and let Org fill in the rest:
|Language|Released|Typing
|-
|Lisp|1958|dynamic
|Haskell|1990|static
|Python|1991|dynamic
Pressing TAB anywhere in it (or C-c C-c, which aligns without moving) turns this into:
| Language | Released | Typing |
|----------+----------+---------|
| Lisp | 1958 | dynamic |
| Haskell | 1990 | static |
| Python | 1991 | dynamic |
Org added the missing closing bars, padded each field, and expanded |- into a full rule. It also decided the alignment of each column: a column that is mostly numbers is right-aligned, any other column is left-aligned. An even faster start is to type only the header line and press C-c RET, which inserts the hline below it and moves to the first body row.
Converting existing data
Data often arrives as CSV, tab-separated text or columns separated by spaces. Select it and press C-c | (org-table-create-or-convert-from-region). Org guesses the separator: tabs if every line has one, commas if every line has one, otherwise white space. Given this CSV:
city,country,population_m
Tokyo,Japan,37.4
Toronto,Canada,6.2
Vancouver,Canada,2.6
C-c | produces:
| city | country | population_m |
| Tokyo | Japan | 37.4 |
| Toronto | Canada | 6.2 |
| Vancouver | Canada | 2.6 |
Add the hline under the first row with C-c - on that row. When the guess is wrong, a prefix argument forces the separator:
| Prefix | Separator |
|---|---|
C-u C-c | | Comma (CSV) |
C-u C-u C-c | | Tab |
C-u C-u C-u C-c | | A regular expression you type |
C-3 C-c | | At least 3 consecutive spaces, or a tab |
Without an active region, C-c | creates an empty table after asking for its size. M-x org-table-import reads a file and converts it the same way. Since Org 9.8 you can also paste a table copied from LibreOffice Calc with M-x yank-media.
Moving around and typing
Inside a table, the common motion keys gain table meanings. Every one of them also re-aligns the table, so you rarely need to think about alignment while typing.
| Key | Command | Effect |
|---|---|---|
TAB | org-table-next-field | Next field; at the end of the table, a new row. |
S-TAB | org-table-previous-field | Previous field. |
RET | org-table-next-row | Same column in the next row; creates a row if needed. |
M-a | org-table-beginning-of-field | Beginning of the field, or the previous field. |
M-e | org-table-end-of-field | End of the field, or the next field. |
C-c C-c | org-table-align | Align without moving. |
Typing inside a field is also special. Characters and DEL do not push the rest of the row to the right; Org takes the space from the padding of the field. And when you type immediately after arriving in a field with TAB, S-TAB or RET, Org clears the field first, so you can overwrite a value without deleting it. If that surprises you more than it helps, set org-table-auto-blank-field to nil.
To edit a field whose content is wider than the column shows, press C-c ` (org-table-edit-field). It opens the field in a small separate window; C-c C-c there writes the result back.
Changing the structure
Rows and columns move with the same M- arrow keys that move headlines and list items, so the muscle memory carries over. Adding S- turns a move into an insertion or deletion.
| Key | Effect on a column | Key | Effect on a row | |
|---|---|---|---|---|
M-LEFT | Move column left | M-UP | Move row up | |
M-RIGHT | Move column right | M-DOWN | Move row down | |
M-S-LEFT | Delete column | M-S-UP | Delete row (or hline) | |
M-S-RIGHT | Insert column | M-S-DOWN | Insert row above (below with C-u) |
S-UP, S-DOWN, S-LEFT and S-RIGHT swap the current field with its neighbor, which is useful for fixing a single misplaced value. C-c - inserts an hline below the current row (above it with C-u), and C-c RET inserts an hline and moves below it.
When you change the structure with these commands, Org also updates absolute references in the table’s formulas so that they keep pointing at the same fields. Editing the text by hand (killing a line with C-k, for example) does not, so prefer the table commands once a table has formulas.
Sorting
C-c ^ (org-table-sort-lines) sorts rows by the column point is in. It sorts the rows between the nearest hlines, so the header and any total row below a rule stay in place. It asks for the sort type:
| Type | Order |
|---|---|
a / A | Alphabetic, ascending / descending |
n / N | Numeric, ascending / descending |
t / T | By time (timestamp or HH:MM), ascending / descending |
f / F | By a key that a function you provide extracts |
Starting from this table:
| Service | Region | Latency (ms) |
|---------+----------+--------------|
| api | eu-west | 42 |
| auth | us-east | 118 |
| search | ap-south | 87 |
| billing | eu-west | 35 |
C-c ^ N in the latency column gives the slowest service first:
| Service | Region | Latency (ms) |
|---------+----------+--------------|
| auth | us-east | 118 |
| search | ap-south | 87 |
| api | eu-west | 42 |
| billing | eu-west | 35 |
and C-c ^ a in the region column on the original table groups rows by region:
| Service | Region | Latency (ms) |
|---------+----------+--------------|
| search | ap-south | 87 |
| api | eu-west | 42 |
| billing | eu-west | 35 |
| auth | us-east | 118 |
With an active region, only the rows in the region are sorted. Alphabetic sorting ignores case unless you add a C-u prefix.
Transposing
M-x org-table-transpose-table-at-point swaps rows and columns. Hlines are dropped, because a horizontal rule has no meaning once rows become columns. The latency table above becomes:
| Service | api | auth | search | billing |
| Region | eu-west | us-east | ap-south | eu-west |
| Latency (ms) | 42 | 118 | 87 | 35 |
Rectangles and wrapping
Ordinary kill and yank work on lines, which is the wrong shape for tables. Org provides rectangle commands that work on fields and ignore hlines:
| Key | Command | Effect |
|---|---|---|
C-c C-x M-w | org-table-copy-region | Copy the fields between point and mark. |
C-c C-x C-w | org-table-cut-region | Copy them and blank the originals. |
C-c C-x C-y | org-table-paste-rectangle | Paste with the upper left corner at point, growing the table if needed. |
M-x org-table-blank-field | Blank the current field or region. |
M-RET (org-table-wrap-region) splits the current field at point and moves the rest into the same column of the next row. With a region inside one column, it rewraps the text of that column across the rows. This is the tool for long text in a table that must stay narrow.
Quick calculations
Two commands help with numbers before you need real formulas:
C-c +(org-table-sum) adds the numbers in the current column, or in the selected rectangle. The result appears in the echo area and is put in the kill ring, soC-yinserts it.S-RET(org-table-copy-down) copies the field above into an empty field, or copies the current field into the next row. Withorg-table-copy-increment(on by default), integers, timestamps and values with a trailing number are incremented, soS-RETonitem-1producesitem-2. AC-0prefix copies without incrementing.
For anything you want to recompute later, use formulas instead; see The Spreadsheet and Plotting.
Column width and alignment
By default Org makes each column as wide as its widest field, and right-aligns a column when most of its fields are numbers. Both choices can be overridden with cookies: short markers in angle brackets placed in a field of their own, anywhere in the column. It is customary to collect them in one row, as in Figure 6.1.
| Cookie | Meaning |
|---|---|
<12> | This column may be shrunk to 12 characters. |
<l>, <c>, <r> | Align the column left, centered or right. |
<r10> | Both: align right, shrink to 10. |
A width cookie does not truncate anything in the file. It tells Org how wide the column should look when it is shrunk. Shrinking is a display feature (an overlay), so the full text is still in the file and still exported:
| Key | Command | Effect |
|---|---|---|
C-c TAB | org-table-toggle-column-width | Shrink or expand the current column. Without a width cookie, the column shrinks to one character. |
C-u C-c TAB | org-table-shrink | Shrink every column that has a width cookie, expand the others. |
C-u C-u C-c TAB | org-table-expand | Expand all columns. |
A shrunk field shows its full text in a tooltip when you hover over it, and C-h . shows it in the echo area. Editing near a shrunk field expands its column again.
To start every visit with shrunk columns, set org-startup-shrink-all-tables or use #+STARTUP: shrink in the file. Similarly, org-startup-align-all-tables and #+STARTUP: align re-align every table when the file opens, which helps when other tools write the file. If automatic re-alignment slows down very large tables, set org-table-automatic-realign to nil and align with C-c C-c when you choose.
A row that contains only cookies is removed when the document is exported. The exporters do not truncate shrunk columns either; ASCII export, for example, widens them back unless org-ascii-table-widen-columns is nil.
Column groups
Exported tables have no vertical lines by default, which usually looks cleaner. When the columns fall into logical groups, vertical lines between the groups help the reader. You define the groups in a special row whose first field is /. In the other fields, < starts a group, > ends one, and <> makes a column a group of its own.
#+OPTIONS: toc:nil num:nil
| Host | CPU % | Mem % | Disk % | Notes |
|-------+-------+-------+--------+------------------------------------|
| / | < | | > | <l20> |
| web-1 | 34 | 61 | 72 | Serves the public site and the API |
| db-1 | 12 | 40 | 55 | Primary database |
The three usage columns form a group, so they appear between two vertical lines. The / row is not exported, and neither is the <l20> cookie in it.
Host | CPU % Mem % Disk % | Notes
-------+----------------------+------------------------------------
web-1 | 34 61 72 | Serves the public site and the API
db-1 | 12 40 55 | Primary database
The HTML exporter expresses the same grouping with three <colgroup> elements, which a style sheet can then draw as borders. It is enough to mark only the start of each group: a < after every place where you want a vertical line produces the same result.
The / marker is one of several marks that Org reads from the first column of a table. The others control recalculation and names and are explained in The Spreadsheet and Plotting.
Exchanging tables with other programs
A table is often the start or the end of a data pipeline. Org can read a table as Lisp data, write it to a file, and translate it into other formats.
Tables as Lisp data
org-table-to-lisp returns the table at point as a list of rows. Each row is a list of strings, and each hline is the symbol hline. For the latency table:
(("Service" "Region" "Latency (ms)") hline ("api" "eu-west" "42") ("auth" "us-east" "118") ("search" "ap-south" "87") ("billing" "eu-west" "35"))
This is the same shape that code blocks receive when a table is passed to them as a variable (see Working with Source Code (Babel)), and the shape that the translators below accept.
Exporting a single table
M-x org-table-export writes the table at point to a file, tab-separated by default (org-table-export-default-format is orgtbl-to-tsv). To fix the file name and format for a table, set the properties TABLE_EXPORT_FILE and TABLE_EXPORT_FORMAT in the entry that contains it:
* Benchmarks
:PROPERTIES:
:TABLE_EXPORT_FILE: latency.csv
:TABLE_EXPORT_FORMAT: orgtbl-to-csv
:END:
Translator functions
The format is a translator: a function that takes the Lisp form of a table and a property list of parameters, and returns a string. Org ships with translators for CSV and TSV (orgtbl-to-csv, orgtbl-to-tsv), for markup languages (orgtbl-to-html, orgtbl-to-latex, orgtbl-to-texinfo), and for Org and Unicode box drawing (orgtbl-to-orgtbl, orgtbl-to-unicode). All of them are built on orgtbl-to-generic, whose docstring lists every parameter. Applied to the latency table, orgtbl-to-csv returns:
Service,Region,Latency (ms)
api,eu-west,42
auth,us-east,118
search,ap-south,87
billing,eu-west,35
and orgtbl-to-latex returns a tabular environment whose column alignment follows the Org table:
\begin{tabular}{llr}
Service & Region & Latency (ms)\\
\hline
api & eu-west & 42\\
auth & us-east & 118\\
search & ap-south & 87\\
billing & eu-west & 35\\
\end{tabular}
A custom format is usually a thin wrapper around orgtbl-to-generic that sets the strings for the start and end of the table and of each line, and the field separator:
(defun my-orgtbl-to-pipe (table params)
(orgtbl-to-generic
table
(org-combine-plists
'(:tstart "BEGIN" :tend "END" :lstart "> " :sep " | ")
params)))
Orgtbl mode: the editor everywhere
The table editor is useful well beyond Org files: in emails, commit messages, plain text notes or comments in source code. Orgtbl mode is a minor mode that provides the editor in any major mode. Toggle it with M-x orgtbl-mode, or enable it for a mode through its hook:
(add-hook 'message-mode-hook #'turn-on-orgtbl)
In Orgtbl mode, the table keys (TAB, RET, C-c C-c, the M- arrows and so on) act on tables only when point is in one; elsewhere they keep their usual meaning in the major mode.
Radio tables
Orgtbl mode can also maintain a table in a syntax the major mode understands, such as LaTeX or HTML, while you edit it as an Org table. This is a radio table: you keep the Org table as the source, hidden in a comment, and Orgtbl mode writes a translated copy between two marker lines.
flowchart LR S["Org table in a comment, after a SEND line"] -- "C-c C-c" --> T["Translator, e.g. orgtbl-to-latex"] T -- "translated text" --> R["Lines between BEGIN RECEIVE and END RECEIVE"] R -- "compiled by" --> P["LaTeX, C compiler, ..."]
Figure 6.2: In a radio table, the Org table is the source of truth and the translated copy is regenerated from it on every send.
Here is a LaTeX file with a radio table. The source table sits inside a comment environment (from the comment package), so LaTeX ignores it:
% BEGIN RECEIVE ORGTBL limits
% END RECEIVE ORGTBL limits
\begin{comment}
#+ORGTBL: SEND limits orgtbl-to-latex
| Setting | Maximum |
|----------+---------|
| retries | 5 |
| timeout | 30 |
| backlog | 128 |
\end{comment}
The #+ORGTBL: SEND line names the table (limits) and the translator. The receiver lines are comments in the host language and carry the same name. With Orgtbl mode on, pressing C-c C-c in the table translates it and replaces everything between the receiver lines:
% BEGIN RECEIVE ORGTBL limits
\begin{tabular}{lr}
Setting & Maximum\\
\hline
retries & 5\\
timeout & 30\\
backlog & 128\\
\end{tabular}
% END RECEIVE ORGTBL limits
Any parameters after the translator name are passed to it as a property list, and they override the translator’s defaults. Two parameters are handled before the translator runs: :skip N drops the first N lines (hlines count), and :skipcols (2 4) drops columns. For LaTeX, :splice t omits the tabular lines so that you can write them yourself.
M-x orgtbl-insert-radio-table inserts a template with the receiver lines and an empty source table for the current major mode. If you cannot hide the source table in a block comment, M-x orgtbl-toggle-comment comments and uncomments its lines.
Summary
- A table is lines starting with
|;|-starts an hline, and rows above the first hline are the header. TAB,RETandC-c C-calign the table; type rough rows and let Org format them.C-c |converts CSV, tab-separated or space-separated text into a table.- The
M-andM-S-arrow keys move, insert and delete rows and columns;C-c ^sorts the rows between hlines. - Cookies like
<10>and<r>control display width and alignment;C-c TABshrinks and expands columns. - A
/row defines column groups, which become vertical lines on export. org-table-to-lisp,org-table-exportand theorgtbl-to-*translators move tables to and from other programs.- Orgtbl mode brings the editor to any buffer, and radio tables keep a translated copy in sync.
Further reading
- Official manual: Tables, Built-in Table Editor, Column Width and Alignment, Column Groups, Orgtbl Mode, Tables in Arbitrary Syntax, Radio tables, Translator functions.
- Source at release 9.8.13: lisp/org-table.el (the editor, Orgtbl mode and the translators).