Plain lists and checkboxes

Plain lists are the lists you write in the body of an entry: bullets, numbers, descriptions and checkboxes. Org understands their structure, so it can renumber them, move items with their sub-items, and count the checked boxes for you. This file goes from simple lists to checkbox statistics.

Start Neovim from the root of the repository with the bundled config:

nvim -u examples/minimal_init.lua examples/03-lists.org

• The file opens folded. <Tab> on a heading opens it, <S-Tab> cycles the whole buffer.
• <prefix> means <leader>o (<Space>o with the bundled config). g? lists every key of the buffer.
• u undoes; git checkout examples/03-lists.org restores the file.
• Try: lines are exercises, Expect: lines say what you should see.
• Lines starting with =# = are comments: notes for you. A comment line in column 0 ends a list, so comments are placed above or below lists, never between their items.
• The bundled config draws checkboxes as icons: [ ] as an empty box, [-] as ◐ and [X] as ✓. The text in the file does not change.
• "On an item" means the cursor is on the first line of the item, usually on its text (not in column 0).

An item starts with a bullet followed by a space: -, +, or * (a star only when the item is indented, because a star in column 0 starts a headline). Lines that belong to an item are indented past its bullet. Items indented under another item form a sub-list.

A list ends:

• at a line that is indented at or left of the first bullet (and is not a new item),
• at a headline,
• or after two blank lines in a row.

Try: open "Groceries" below. Put the cursor on "Fruit" and press <Tab>, then <Tab> again.

Expect: the first <Tab> folds "Fruit": its sub-items "apples" and "pears" and its second line are hidden, the line ends with .... The second <Tab> shows them again. (cycle_include_plain_lists = true, the default, makes items with sub-items or several lines foldable.)

Ordered bullets are a number followed by . or ): 1., 1). You never renumber by hand: every list command renumbers the list when it changes it. If the numbers are wrong (you typed them, or pasted lines), <C-c><C-c> on the first line of an item repairs the whole list.

A counter [@N] right after the bullet makes the list continue from N.

Try: put the cursor on "Wake up" (in "Wrong numbers") and press <C-c><C-c>.

Expect: the numbers become 1, 2, 3, 4:

1. Wake up
2. Make coffee
3. Drink coffee
4. Work

Try: in "Counter", press <C-c><C-c> on "Chapter five".

Expect: the numbers stay 5, 6, 7: the list starts at the counter. Change [@5] to [@10] and press <C-c><C-c> again: 10, 11, 12.

A description item has a term, then :: surrounded by spaces, then the description. It is an unordered item (- or +), and it is exported as a definition list (<dl> in HTML).

Try: on "Neovim" press $ (end of line) then <M-CR>, type Emacs, press <Esc>.

Expect: a new description item right after "Neovim", with the separator already there and the cursor on the term:

- Emacs ::

<M-CR> (Meta-Return) on an item inserts a new item of the same kind (bullet, description term) and leaves you in Insert mode. Where:

• Normal mode, anywhere on the item's first line (even column 0): after the item and its sub-items.
• Insert mode: at the cursor. At or before the item text (e.g. i in column 0) the new item goes above; in the middle of the text, the rest of the text moves to the new item.

<M-S-CR> does the same but adds an empty checkbox [ ]. <prefix>is inserts a sub-item (indented one level). A new item never copies the checkbox of the current one with <M-CR>.

In Insert mode, right after <M-CR>, <Tab> on the new empty item cycles its indentation: under the previous item, then back out level by level.

When the items of a list are separated by blank lines, new items get a blank line too (blank_before_new_entry = { plain_list_item = "auto" }).

Try: on "Saturday" press $ and <M-CR>, type Sunday, <Esc>.

Expect: - Sunday after "Saturday" (and after its sub-item "morning run"), before "Next week".

Try: on "Saturday" press $ and <M-S-CR>, type Pack, <Esc>.

Expect: - [ ] Pack after the "Saturday" item.

Try: on "Saturday" press $ and <prefix>is, type evening, <Esc>.

Expect: an indented sub-item = - evening= right below "Saturday".

Try: on "Next week" press A, then <M-CR>, then <Tab>, type Monday and <Esc>.

Expect: = - Monday= indented under "Next week".

Try: on "Split this item" put the cursor on i of "item", press i and <M-CR>, then <Esc>.

Expect: two items: - Split this and - item.

<S-Right> / <S-Left> on an item cycle the bullet of the whole list (the item and its siblings) through -, +, *, 1., 1). The star is skipped for a list in column 0. Sub-lists keep their own bullets. <prefix>hb and <C-c>- cycle forward too.

Try: on "alpha" (in "Cycle me") press <S-Right> four times.

Expect: the bullets of alpha, beta and gamma become +, then 1. 2. 3., then 1) 2) 3), then - again. The sub-item "beta one" keeps its - bullet (and moves right when the numbers make the bullet wider).

<S-Down> / <S-Up> jump to the next / previous item of the same level, skipping sub-items.

Try: on "Ann" press <S-Down> twice.

Expect: the cursor goes to "Bob" (skipping "Ann's notes"), then to "Cid".

Org's list rules apply:

• The first item of a list cannot be indented alone; <M-L> / <M-H> on it move the whole list.
• An item with sub-items cannot be outdented alone: use <s or <M-H>.
• After each change the list is repaired: numbering, bullets, the indentation of sub-lists and parent checkboxes.
• In Visual mode, <M-l> / <M-h> indent / outdent every selected item.

Try: on "Task B" press >s.

Expect: "Task B" and its sub-item "B detail" move right together; "Task B" is now a sub-item of "Task A":

- Task A
  - Task B
    - B detail
- Task C

Try: press u, then >> on "Task B".

Expect: only "Task B" moves; "B detail" stays where it was and becomes its sibling:

- Task A
  - Task B
  - B detail

Try: press u, then >> on "Task A".

Expect: nothing changes and a message says "At first item: use S-M-<left/right> to move the whole list".

Try: on "Nested parent" (in "Outdent rules") press <<.

Expect: the message "Cannot outdent an item without its children". Press <s instead: "Nested parent" and "Nested child" both move left.

<M-k> / <M-j> (also <M-Up> / <M-Down>) move an item up / down past its sibling. Sub-items, extra lines and checkboxes travel with it, and ordered lists are renumbered.

Try: on "Third" press <M-k> twice.

Expect:

1. Third
2. First
3. Second

The numbers stay in order; only the texts moved.

Try: on "Unpacked" press <M-j>.

Expect: "Unpacked" moves below "Packed" together with its sub-item:

- [X] Packed
- [ ] Unpacked
  - [ ] socks

In Visual mode <prefix>- converts every selected line; with a count the selection becomes a single item.

Try: select the three lines "eggs", "flour" and "sugar" (in "Text to items") with V and 2j, then press <prefix>-.

Expect:

- eggs
- flour
- sugar

Try: in "Items to headlines", on "[ ] Book the venue" press <C-c><C-*>.

Expect: the list is gone; its items are now child headlines of "Items to headlines", with checkboxes turned into keywords and sub-items into deeper headlines:

*** TODO Book the venue
*** DONE Send the invitations
**** DONE Family
**** DONE Friends

An item becomes a task when it starts with a checkbox: [ ] (open), [X] (done) or [-] (partly done, set automatically).

• <C-Space> (or <C-c><C-c>, or Emacs <C-c><C-x><C-b>) on the first line of an item toggles its box.
• A parent box follows its children: when some children are done it shows [-], when all are done [X]. Toggling the parent itself is refused ("Cannot toggle this checkbox").
• With a count: 4<C-c><C-c> adds (or removes) a checkbox on the item; 16<C-c><C-c> sets [-].
• In Visual mode, <C-Space> toggles every selected item (following the state of the first one).
• On a headline, <C-Space> toggles every item of its text.

Try: in "Packing", toggle "Passport" and "Tickets" with <C-Space>.

Expect: "Documents" first becomes [-] (after Passport), then [X] (after Tickets). "Documents" was never toggled by you.

Try: on "Documents" press <C-c><C-c>.

Expect: nothing changes, and the message "Cannot toggle this checkbox: all subitems checked" appears. (<C-Space> silently leaves it alone.)

Try: on "Toothbrush" (no box yet) press 4<C-c><C-c>.

Expect: - [ ] Toothbrush. Press 4<C-c><C-c> again to remove it.

Try: select "Shirts", "Socks" and "Shoes" with V2j and press <C-Space>.

Expect: all three become [X].

A cookie [/] or [%] at the end of an item or a headline shows how many of its checkboxes are done: [2/5] or [40%]. Type the empty cookie yourself; Org fills it in and updates it after every toggle. You can put both on the same line.

• On an item, the cookie counts its direct sub-items.
• On a headline, it counts the top-level items of its text (sub-items are counted through their parents), or, when there are no checkboxes, its child TODO entries (see 04-todo.org).
• <prefix># (Emacs <C-c>#) updates the cookies of the current entry; 4<prefix># updates every cookie of the buffer.

Try: go to "Party [/] [%]" below and press <prefix># on its headline.

Expect: the headline shows [1/3] [33%] (one of its three top-level items, "Music", is checked). "Food" shows [1/2].

Try: check "Snacks".

Expect: "Food" becomes [X] with [2/2], and the headline becomes [2/3] [66%].

A radio list allows only one checked item: checking one unchecks the others. Mark the list with #+attr_org: :radio t on the line above it; then <C-c><C-c> and <C-Space> work like radio buttons. <C-c><C-x><C-r> (:Org toggle_radio_button) toggles a radio button in any list, and :Org checkbox_radio_mode makes <C-c><C-c> behave that way in every list of the buffer.

Try: in "Coffee size", press <C-c><C-c> on "Large".

Expect: "Large" is checked and "Medium" is unchecked.

Try: in "Normal list", put the cursor on "red" and press <C-c><C-x><C-r>.

Expect: "red" is checked and "green" unchecked, although this list has no :radio attribute.

<prefix>hs (Emacs <C-c>^) on an item sorts that item and its siblings. The menu has fewer keys than for headlines:

Uppercase keys reverse the order; a count makes a case-sensitive. Sub-items travel with their item, and ordered lists are renumbered.

Try: on "cherry" press <prefix>hs then a.

Expect: apple, banana (with its sub-item), cherry, numbered 1, 2, 3.

Try: on any item of "Chores list" press <prefix>hs then x.

Expect: the open items first, each group in its original order:

- [ ] vacuum
- [ ] windows
- [X] dishes
- [X] laundry

Press <prefix>hs then X (reverse) to get the checked ones first.

Try: on "Retro" press <prefix>hs then t.

Expect: Kickoff (Oct 1), Review (Oct 14), Retro (Nov 2).

With enforce_todo_checkbox_dependencies = true, an entry cannot be marked DONE while it has unchecked boxes. It is off by default; for this session:

:lua require("org.config").opts.enforce_todo_checkbox_dependencies = true

Try: turn it on, then on "Ship the release" press cit (next TODO state).

Expect: the entry stays TODO and a message says it is blocked. Check both boxes and press cit again: it becomes DONE.

Not available (Emacs options without an org.nvim equivalent): alphabetical bullets (a., org-list-allow-alphabetical), changing the bullet automatically when demoting (org-list-demote-modify-bullet) and a custom indentation of sub-lists (org-list-indent-offset).

Timer lists (items whose term is a running time, 0:05:12 ::) are covered in 20-timers-reminders.org.

:h org-lists

lists, checkboxes and cookies

:h org-radio-list

radio buttons

:h org-meta-return

<M-CR> in lists

:h org-promote-demote

indentation rules for items

:h org-sort

sorting lists

:h org-todo-statistics

cookies that count TODO entries