docs/manual/guide/10-tables.org

A table is a run of lines that start with |. Fields are separated by |, and a line that starts with |- is a horizontal rule:

| Name  | Qty | Price |
|-------+-----+-------|
| Apple |   3 |  0.50 |
| Pear  |  12 |  0.75 |

Orgstar follows org-table.el from Org 9.8.7, with org-table-automatic-realign on, org-table-tab-jumps-over-hlines on, and formulas adjusted without asking when rows and columns move (org-table-fix-formulas-confirm nil). Tables inside dynamic blocks count as tables; tables inside other blocks don't.

Type |, a few field names separated by |, and press TAB: Orgstar aligns the line as a table and moves to the next field, adding a row after the last one. Type |- on the line below a row and press TAB to turn it into a full-width rule.

org-table-create-or-convert-from-region builds one for you: C-c | in the Emacs and Doom presets, ⌃⌘\ in the Mac preset.

With no selection it asks Table size Columns x Rows [e.g. 5x2]:. An empty answer makes a 5 × 2 table. When there is more than one row, a rule follows the first row.

With text selected, the command converts the selected lines to a table instead (org-table-convert-region). The separator is guessed:

• tabs, when every line has a tab;
• otherwise commas, when every line has a comma, read as CSV: a field in double quotes can hold commas, and a line break in it becomes a space;
• otherwise runs of spaces.

These keys work the same in the Emacs and Mac presets. In Doom they apply in insert state; in normal state RET is Doom's "act at point" (see Recalculating).

Alignment (org-table-align) pads every field to its column's width and redraws rules to match. A column is right-aligned when at least half of its non-empty fields are numbers, and left-aligned otherwise. A field that holds only a cookie <l>, <c> or <r> (optionally with a width, such as <r10>) fixes the column's alignment. Widths count display columns, so wide characters and hidden link markup are measured as they appear.

Alignment happens when you press TAB, S-TAB or RET in a table and after every table command, not while you type. To align without moving, use Org ▸ Align Table:

C-c C-c (Mac ⌃⌘X) in a table is org-ctrl-c-ctrl-c, as in Emacs. It first evaluates a formula typed in the current field (see Entering formulas). Then, in a row marked # (see Names, parameters and constants), it recalculates that row, which also aligns the table; in any other row it aligns the table. With the caret at the table's very first character, it recalculates the whole table instead.

To align every table when a file opens, set org-startup-align-all-tables to true in the config file (default false), or put #+STARTUP: align in the file; #+STARTUP: noalign turns it off for that file. See Configuration.

The new column goes to the left of the caret's column, empty. Deleting a row deletes the line; it doesn't go to the clipboard. When rows and columns move, are inserted or are deleted, the #+TBLFM line is updated to match: references are renumbered, and formulas for a deleted row or column are removed.

The Mac preset uses the same keys for headings and list items; in a table they act on the table.

A field that holds a width cookie <N>, optionally with an alignment letter (<l10>, <c8>, <r12>), marks the column for narrowing. Narrowed fields show their first N display columns followed by …. The text itself is unchanged.

C-c TAB in a field toggles that column. Outside a column, for example on the leading |, it asks for Column ranges (e.g. 2-4 6-):, where 6- means column 6 to the end. A column without a width cookie shrinks to a bare … when toggled. Typing in a narrowed field widens its column again, as editing Org's overlays does. #+STARTUP: shrink narrows every column with a width cookie when the file opens.

The iOS editor narrows columns the same way, with #+STARTUP: shrink and the three commands, which are in Commands when the caret is in a table. The iOS reader shows tables at full width.

Open the command palette with ⇧⌘P (M-x in the Emacs preset, SPC : in Doom).

Import asks for a CSV, TSV or plain text file, inserts its contents at the caret on a line of its own, and converts them to a table with the separator guessed as for a region (see Creating a table).

Export writes the table at the caret. A file name ending in .csv gets CSV: fields separated by commas, with fields that contain a comma or a double quote quoted and inner quotes doubled. Any other name gets TSV. Rules are left out.

Import and export are Mac only.

Orgstar evaluates Org's spreadsheet formulas, org-table-recalculate and org-table-eval-formula, natively: Calc expressions in a reimplementation of the part of Emacs Calc that tables use, and Lisp formulas in a small Emacs Lisp evaluator. What falls outside them is handed to Emacs on the Mac (see When Emacs is needed).

Formulas live in a #+TBLFM: line right after the table, separated by :::

| Item  | Qty | Price | Total |
|-------+-----+-------+-------|
| Apple |   3 |  0.50 |  1.50 |
| Pear  |  12 |  0.75 |  9.00 |
|-------+-----+-------+-------|
| Sum   |     |       | 10.50 |
#+TBLFM: $4=$2*$3;%.2f::@>$4=vsum(@I..@II);%.2f

Blank lines between the table and #+TBLFM: are allowed. If there are several #+TBLFM: lines, recalculating the table uses the first; C-c C-c on another applies that line instead (org-table-calc-current-TBLFM).

| ! | qty | price | total |
|---+-----+-------+-------|
| # |   2 |     3 |     6 |
| # |   4 |   0.5 |     2 |
#+TBLFM: $4=$qty*$price

#+NAME: rates
| item | rate |
|------+------|
| a    |    2 |
| b    |    3 |

| x | y | z |
|---+---+---|
| 4 | 8 | 5 |
#+TBLFM: $2=$1*remote(rates,@2$2)::$3=vsum(remote(rates,@2$2..@>$2))

| start    | end     | sum      | diff  | hours |
|----------+---------+----------+-------+-------|
| 1:30     | 0:45    | 02:15:00 | 00:45 |  3.00 |
| 10:00:30 | 2:15:10 | 12:15:40 | 07:45 | 20.02 |
#+TBLFM: $3=$1+$2;T::$4=$1-$2;U::$5=$1*2;t

| start            | end              | days | later            |
|------------------+------------------+------+------------------|
| <2026-10-05 Mon> | <2026-10-12 Mon> |    7 | [2026-10-12 Mon] |
#+TBLFM: $3=$2-$1::$4=$1+7

| name  | greeting |
|-------+----------|
| Ada   | Ada!     |
| Grace | Grace!   |
#+TBLFM: $2='(concat $1 "!")

| n |
|---|
| 1 |
| 2 |
|---|
| 3 |
#+TBLFM: @>$1='(apply '+ '(@I..@II));N

There are three ways to set a formula.

In the field. Type =expr in a field and press TAB or RET: Orgstar stores $N=expr as the column's formula and evaluates it, as org-table-maybe-eval-formula does. Type :=expr instead to store a field formula @R$C=expr.

With a prompt. org-table-eval-formula asks for the formula (Column formula $N= or Field formula @R$C=) with the stored one filled in, stores it and evaluates it in the current field. Clearing the prompt and pressing Return removes the stored formula, as in Emacs, and the echo area shows Formula removed. You can also delete a formula in the formula editor below or from the #+TBLFM: line.

Org's C-u C-c = for field formulas has no equivalent key, because Orgstar has no prefix argument; use the menu item or type := in the field.

In the formula editor. C-c ' in a table or on its #+TBLFM: line (org-table-edit-formulas) opens the formulas in an editor of their own, one per line, grouped under # Column Formulas, # Field and Range Formulas and # Named Field Formulas. A formula can continue on indented lines. C-c ' or ⌘Return installs the formulas; Escape or C-c C-k leaves them unchanged. Installing doesn't recalculate. The echo area says so and points to Recalculate Table: C-c C-c on the #+TBLFM: line, or ⌃⌘X there in the Mac preset.

The formulas are stored sorted the way org-table-formula-less-p sorts them.

In Doom's normal state, RET in a table recalculates it when it has a #+TBLFM: line and aligns it otherwise; on a #+TBLFM: line it recalculates.

When the table has a rule below its first data row, recalculating the whole table leaves the rows above that rule, the header, alone. With marked rows, the marks decide instead (see Names, parameters and constants). Each command evaluates the column formulas row by row, then the field formulas, then aligns the table. Formulas are evaluated once; Org's iterate-until-stable recalculation (C-u C-u C-c *) isn't available.

Tables are not recalculated automatically. Rows marked # are not recalculated when you press TAB or RET in them, as org-table-maybe-recalculate-line would do in Emacs; recalculate with one of the commands above, or with C-c C-c (Mac ⌃⌘X) in the row.

When a formula uses something the native evaluator doesn't have, the command reports what it was and the Mac recalculates the table in Emacs instead. This happens for:

• references to fields holding text in a Calc formula, and symbolic results;
• Calc functions and variables not listed above, precision other than p12, and the S and u flags;
• division by zero, complex results, vector results, and numbers too large for 64-bit integers;
• Lisp functions not listed above.

The echo area shows Recalculating in Emacs (reason)…, then Recalculated in Emacs. Orgstar runs emacs -Q --batch on a copy of the file, so your Emacs init file, packages and customizations are not loaded, then replaces the table with Emacs's result. It looks for Emacs at the path in the ORGSTAR_EMACS environment variable, then /opt/homebrew/bin/emacs, /usr/local/bin/emacs, /Applications/Emacs.app/Contents/MacOS/Emacs, /run/current-system/sw/bin/emacs and /usr/bin/emacs. If none is found, the echo area says Emacs isn't installed and the table is unchanged. Emacs gets your PATH with /opt/homebrew/bin, /usr/local/bin, /Library/TeX/texbin, /usr/bin and /bin added, as code blocks and export do, so programs a formula starts are found when Orgstar was opened from the Dock. The run stops after 60 seconds. If you edit the table while Emacs is working, its result is discarded.

Edit ▸ Cancel Running Task (⌘.) stops the recalculation; the echo area shows Recalculation canceled and the table is unchanged. Starting another recalculation or export in Emacs cancels the one that is running.

If the table's formulas contain Lisp, Orgstar asks first: This table's formulas run Lisp. Run them? (yes, no, always). always trusts this table's text in this file, so the question isn't asked again until the text changes.

Entering a formula that needs Emacs with C-c =, Set Field Formula or = in a field is not handed to Emacs. The formula is stored in the #+TBLFM: line and the field is left as it was; the echo area shows The formula was stored; recalculating it needs Emacs and the reason. TAB and RET still move to the next field. Recalculate the table to run the formula in Emacs.

For how Orgstar and Emacs share files, see Using Orgstar alongside Emacs.

Tables drawn with + corners and - and | borders, as the table.el package makes them, are recognized and kept as written:

+-------+-------+
| Name  | Value |
+-------+-------+
| a     | 1     |
+-------+-------+

Orgstar doesn't edit them as tables: TAB, alignment and formulas don't apply. HTML export renders them as tables, with cells that span rows and columns, and Markdown export writes them as a code block. See Export.

#+PLOT: lines are recognized and completed as keywords, but Orgstar doesn't draw plots (org-plot/gnuplot is not available).

The iOS app evaluates formulas natively with the same engine. Tables that need Emacs are not recalculated there; the app reports This table needs Emacs, which runs on the Mac with the reason. Table import and export are Mac only. Narrow columns work in the editor, as described under Narrow columns. See iOS.