5.6 Checkboxes ¶

Every item in a plain list⁴⁷ (see Plain Lists) can be made into a checkbox by starting it with the string ‘[ ]’. This feature is similar to TODO items (see TODO Items), but is more lightweight. Checkboxes are not included into the global TODO list, so they are often great to split a task into a number of simple steps. Or you can use them in a shopping list.

Here is an example of a checkbox list.

* TODO Organize party [2/4]
  - [-] call people [1/3]
    - [ ] Peter
    - [X] Sarah
    - [ ] Sam
  - [X] order food
  - [ ] think about what music to play
  - [X] talk to the neighbors

The ‘[2/4]’ and ‘[1/3]’ in the first and second line are cookies indicating how many checkboxes present in this entry have been checked off, and the total number of checkboxes present. This can give you an idea on how many checkboxes remain, even without opening a folded entry. The cookies can be placed into a headline or into (the first line of) a plain list item. Each cookie covers checkboxes of direct children structurally below the headline/item on which the cookie appears⁴⁸. You have to insert the cookie yourself by typing either ‘[/]’ or ‘[%]’. With ‘[/]’ you get an ‘n out of m’ result, as in the examples above. With ‘[%]’ you get information about the percentage of checkboxes checked (in the above example, this would be ‘[50%]’ and ‘[33%]’, respectively). In a headline, a cookie can count either checkboxes below the heading or TODO states of children, and it displays whatever was changed last. Set the property ‘COOKIE_DATA’ to either ‘checkbox’ or ‘todo’ to resolve this issue.

If the current outline node has an ‘ORDERED’ property, checkboxes must be checked off in sequence, and an error is thrown if you try to check off a box while there are unchecked boxes above it.

A checkbox can be in one of the three states:

1. not checked ‘[ ]’
2. partially checked ‘[-]’
3. checked ‘[X]’

Checkboxes work hierarchically, so if a checkbox item has children that are checkboxes, toggling one of the children checkboxes makes the parent checkbox reflect if none, some, or all of the children are checked.

If all child checkboxes are not checked, the parent checkbox is also not checked.

- [ ] call people
  - [ ] Peter
  - [ ] Sarah

If some but not all child checkboxes are checked, the parent checkbox is partially checked.

- [-] call people
  - [X] Peter
  - [ ] Sarah

If all child checkboxes are checked, the parent checkbox is also checked.

- [X] call people
  - [X] Peter
  - [X] Sarah

The following commands work with checkboxes:

C-c C-c (org-toggle-checkbox) ¶

Toggle checkbox status or—with prefix argument—checkbox presence at point. With a single prefix argument, add an empty checkbox or remove the current one⁴⁹. With a double prefix argument, set it to ‘[-]’, which is considered to be an intermediate state.

C-c C-x C-b (org-toggle-checkbox) ¶

Toggle checkbox status or—with prefix argument—checkbox presence at point. With double prefix argument, set it to ‘[-]’, which is considered to be an intermediate state.

• If there is an active region, toggle the first checkbox in the region and set all remaining boxes to the same status as the first. With a prefix argument, add or remove the checkbox for all items in the region.
• If point is in a headline, toggle checkboxes in the region between this headline and the next—so not the entire subtree.
• If there is no active region, just toggle the checkbox at point.

C-c C-x C-r (org-toggle-radio-button) ¶

Toggle checkbox status by using the checkbox of the item at point as a radio button: when the checkbox is turned on, all other checkboxes on the same level will be turned off. With a universal prefix argument, toggle the presence of the checkbox. With a double prefix argument, set it to ‘[-]’.

C-c C-c can be told to consider checkboxes as radio buttons by setting ‘#+ATTR_ORG: :radio t’ right before the list or by calling M-x org-list-checkbox-radio-mode to activate this minor mode.

M-S-RET (org-insert-todo-heading) ¶

Insert a new item with a checkbox. This works only if point is already in a plain list item (see Plain Lists).

C-c C-x o (org-toggle-ordered-property) ¶

Toggle the ‘ORDERED’ property of the entry, to toggle if checkboxes must be checked off in sequence. A property is used for this behavior because this should be local to the current entry, not inherited like a tag. However, if you would like to track the value of this property with a tag for better visibility, customize org-track-ordered-property-with-tag.

C-c # (org-update-statistics-cookies) ¶

Update the statistics cookie in the current outline entry. When called with a C-u prefix, update the entire file. Checkbox statistic cookies are updated automatically if you toggle checkboxes with C-c C-c and make new ones with M-S-RET. TODO statistics cookies update when changing TODO states. If you delete boxes/entries or add/change them by hand, use this command to get things back into sync.