Skip to main content

3.1 Built-in Table Editor

Org makes it easy to format tables in plain ASCII. Any line with ‘|’ as the first non-whitespace character is considered part of a table. ‘|’ is also the column separator1. Moreover, a line starting with ‘|-’ is a horizontal rule. It separates rows explicitly. Rows before the first horizontal rule are header lines. A table might look like this:

| Name  | Phone | Age |
|-------+-------+-----|
| Peter |  1234 |  17 |
| Anna  |  4321 |  25 |

A table is re-aligned automatically each time you press TAB, RET or C-c C-c inside the table. TAB also moves to the next field—RET to the next row—and creates new table rows at the end of the table or before horizontal lines. The indentation of the table is set by the first line. Horizontal rules are automatically expanded on every re-align to span the whole table width. So, to create the above table, you would only type

|Name|Phone|Age|
|-

and then press TAB to align the table and start filling in fields. Even faster would be to type ‘|Name|Phone|Age’ followed by C-c RET.

When typing text into a field, Org treats DEL, Backspace, and all character keys in a special way, so that inserting and deleting avoids shifting other fields. Also, when typing immediately after point was moved into a new field with TAB, S-TAB or RET, the field is automatically made blank. If this behavior is too unpredictable for you, configure the option org-table-auto-blank-field.

Creation and conversion​

C-c | (org-table-create-or-convert-from-region)​

Convert the active region to table. If every line contains at least one TAB character, the function assumes that the material is tab separated. If every line contains a comma, comma-separated values (CSV) are assumed. If not, lines are split at whitespace into fields. You can use a prefix argument to force a specific separator: C-u forces CSV, C-u C-u forces TAB, C-u C-u C-u prompts for a regular expression to match the separator, and a numeric argument N indicates that at least N consecutive spaces, or alternatively a TAB will be the separator.

If there is no active region, this command creates an empty Org table. But it is easier just to start typing, like | N a m e | P h o n e | A g e RET | - TAB.

Re-aligning and field motion​

C-c C-c (org-table-align)​

Re-align the table without moving point.

TAB (org-table-next-field)​

Re-align the table, move to the next field. Creates a new row if necessary.

C-c SPC (org-table-blank-field)​

Blank the field at point.

S-TAB (org-table-previous-field)​

Re-align, move to previous field.

RET (org-table-next-row)​

Re-align the table and move down to next row. Creates a new row if necessary. At the beginning or end of a line, RET still inserts a new line, so it can be used to split a table.

M-a (org-table-beginning-of-field)​

Move to beginning of the current table field, or on to the previous field.

M-e (org-table-end-of-field)​

Move to end of the current table field, or on to the next field.

Column and row editing​

M-LEFT (org-table-move-column-left)​

Move the current column left.

M-RIGHT (org-table-move-column-right)​

Move the current column right.

M-S-LEFT (org-table-delete-column)​

Kill the current column.

M-S-RIGHT (org-table-insert-column)​

Insert a new column at point position. Move the recent column and all cells to the right of this column to the right.

M-UP (org-table-move-row-up)​

Move the current row up.

M-DOWN (org-table-move-row-down)​

Move the current row down.

M-S-UP (org-table-kill-row)​

Kill the current row or horizontal line.

S-UP (org-table-move-cell-up)​

Move cell up by swapping with adjacent cell.

S-DOWN (org-table-move-cell-down)​

Move cell down by swapping with adjacent cell.

S-LEFT (org-table-move-cell-left)​

Move cell left by swapping with adjacent cell.

S-RIGHT (org-table-move-cell-right)​

Move cell right by swapping with adjacent cell.

M-S-DOWN (org-table-insert-row)​

Insert a new row above the current row. With a prefix argument, the line is created below the current one.

C-c - (org-table-insert-hline)​

Insert a horizontal line below current row. With a prefix argument, the line is created above the current line.

C-c RET (org-table-hline-and-move)​

Insert a horizontal line below current row, and move point into the row below that line.

C-c ^ (org-table-sort-lines)​

Sort the table lines in the region. The position of point indicates the column to be used for sorting, and the range of lines is the range between the nearest horizontal separator lines, or the entire table. If point is before the first column, you are prompted for the sorting column. If there is an active region, the mark specifies the first line and the sorting column, while point should be in the last line to be included into the sorting. The command prompts for the sorting type, alphabetically, numerically, or by time. You can sort in normal or reverse order. You can also supply your own key extraction and comparison functions. When called with a prefix argument, alphabetic sorting is case-sensitive.

Regions​

C-c C-x M-w (org-table-copy-region)​

Copy a rectangular region from a table to a special clipboard. Point and mark determine edge fields of the rectangle. If there is no active region, copy just the current field. The process ignores horizontal separator lines.

C-c C-x C-w (org-table-cut-region)​

Copy a rectangular region from a table to a special clipboard, and blank all fields in the rectangle. So this is the “cut" operation.

C-c C-x C-y (org-table-paste-rectangle)​

Paste a rectangular region into a table. The upper left corner ends up in the current field. All involved fields are overwritten. If the rectangle does not fit into the present table, the table is enlarged as needed. The process ignores horizontal separator lines.

M-RET (org-table-wrap-region)​

Split the current field at point position and move the rest to the line below. If there is an active region, and both point and mark are in the same column, the text in the column is wrapped to minimum width for the given number of lines. A numeric prefix argument may be used to change the number of desired lines. If there is no region, but you specify a prefix argument, the current field is made blank, and the content is appended to the field above.

Calculations​

C-c + (org-table-sum)​

Sum the numbers in the current column, or in the rectangle defined by the active region. The result is shown in the echo area and can be inserted with C-y.

S-RET (org-table-copy-down)​

When current field is empty, copy from first non-empty field above. When not empty, copy current field down to next row and move point along with it.

Depending on the variable org-table-copy-increment, integer and time stamp field values, and fields prefixed or suffixed with a whole number, can be incremented during copy. Also, a 0 prefix argument temporarily disables the increment.

This key is also used by shift-selection and related modes (see Conflicts).

Miscellaneous​

C-c ` (org-table-edit-field)​

Edit the current field in a separate window. This is useful for fields that are not fully visible (see Column Width and Alignment). When called with a C-u prefix, just make the full field visible, so that it can be edited in place. When called with two C-u prefixes, make the editor window follow point through the table and always show the current field. The follow mode exits automatically when point leaves the table, or when you repeat this command with C-u C-u C-c `.

M-x org-table-import​

Import a file as a table. The table should be TAB or whitespace separated. Use, for example, to import a spreadsheet table or data from a database, because these programs generally can write TAB-separated text files. This command works by inserting the file into the buffer and then converting the region to a table. Any prefix argument is passed on to the converter, which uses it to determine the separator.

C-c | (org-table-create-or-convert-from-region)​

Tables can also be imported by pasting tabular text into the Org buffer, selecting the pasted text with C-x C-x and then using the C-c | command (see Creation and conversion).

M-x org-table-export​

Export the table, by default as a TAB-separated file. Use for data exchange with, for example, spreadsheet or database programs. The format used to export the file can be configured in the variable org-table-export-default-format. You may also use properties ‘TABLE_EXPORT_FILE’ and ‘TABLE_EXPORT_FORMAT’ to specify the file name and the format for table export in a subtree. Org supports quite general formats for exported tables. The exporter format is the same as the format used by Orgtbl radio tables, see Translator functions, for a detailed description.

M-x org-table-header-line-mode​

Turn on the display of the first data row of the table at point in the window header line when this first row is not visible anymore in the buffer. You can activate this minor mode by default by setting the option org-table-header-line-p to t.

M-x org-table-transpose-table-at-point​

Transpose the table at point and eliminate hlines.

  1. To insert a vertical bar into a table field, use ‘\vert’ or, inside a word ‘abc\vert{}def’.↩