Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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:

PartHow Org recognizes itPurpose
#+NAME: lineA keyword directly above the tableLets links and formulas in other tables refer to this table.
Header rowsRows above the first hlineColumn titles; exported as table headers and left alone by column formulas.
HlineA line starting with |-Separates header from body, or groups of rows.
Cookie rowA row with only <N>, <l>, <c>, <r> or column-group markersDisplay width and alignment; removed on export.
FieldText between two barsOne value. Leading and trailing spaces are not part of the value.
#+TBLFM: lineA keyword directly below the tableThe 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:

PrefixSeparator
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.

KeyCommandEffect
TABorg-table-next-fieldNext field; at the end of the table, a new row.
S-TABorg-table-previous-fieldPrevious field.
RETorg-table-next-rowSame column in the next row; creates a row if needed.
M-aorg-table-beginning-of-fieldBeginning of the field, or the previous field.
M-eorg-table-end-of-fieldEnd of the field, or the next field.
C-c C-corg-table-alignAlign 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.

KeyEffect on a columnKeyEffect on a row
M-LEFTMove column leftM-UPMove row up
M-RIGHTMove column rightM-DOWNMove row down
M-S-LEFTDelete columnM-S-UPDelete row (or hline)
M-S-RIGHTInsert columnM-S-DOWNInsert 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:

TypeOrder
a / AAlphabetic, ascending / descending
n / NNumeric, ascending / descending
t / TBy time (timestamp or HH:MM), ascending / descending
f / FBy 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:

KeyCommandEffect
C-c C-x M-worg-table-copy-regionCopy the fields between point and mark.
C-c C-x C-worg-table-cut-regionCopy them and blank the originals.
C-c C-x C-yorg-table-paste-rectanglePaste with the upper left corner at point, growing the table if needed.
M-x org-table-blank-fieldBlank 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, so C-y inserts it.
  • S-RET (org-table-copy-down) copies the field above into an empty field, or copies the current field into the next row. With org-table-copy-increment (on by default), integers, timestamps and values with a trailing number are incremented, so S-RET on item-1 produces item-2. A C-0 prefix 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.

CookieMeaning
<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:

KeyCommandEffect
C-c TABorg-table-toggle-column-widthShrink or expand the current column. Without a width cookie, the column shrinks to one character.
C-u C-c TABorg-table-shrinkShrink every column that has a width cookie, expand the others.
C-u C-u C-c TABorg-table-expandExpand 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, RET and C-c C-c align 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- and M-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 TAB shrinks and expands columns.
  • A / row defines column groups, which become vertical lines on export.
  • org-table-to-lisp, org-table-export and the orgtbl-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