Every item in a plain list54 (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 in 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. To toggle a checkbox, use C-c C-c, or use the mouse (thanks to Piotr Zielinski’s org-mouse.el).
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
Checkboxes work hierarchically, so if a checkbox item has children that are checkboxes, toggling one of the children checkboxes will make the parent checkbox reflect if none, some, or all of the children are checked.
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 appears55. 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
will display whatever was changed last. Set the property
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 will be thrown if you try to check
off a box while there are unchecked boxes above it.
The following commands work with checkboxes:
Toggle checkbox status or (with prefix arg) checkbox presence at point. With a single prefix argument, add an empty checkbox or remove the current one56. With a double prefix argument, set it to ‘[-]’, which is considered to be an intermediate state.
Toggle checkbox status or (with prefix arg) checkbox presence at point. With double prefix argument, set it to ‘[-]’, which is considered to be an intermediate state.
Insert a new item with a checkbox. This works only if the cursor is already in a plain list item (see Plain lists).
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
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.
With the exception of description
lists. But you can allow it by modifying
Set the option
org-checkbox-hierarchical-statistics if you want such cookies to
count all checkboxes below the cookie, not just those belonging to direct
C-u C-c C-c before the first bullet in a list with no checkbox will add checkboxes to the rest of the list.