Previous: Breaking down tasks, Up: TODO Items

5.6 Checkboxes

Every item in a plain list1 (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 appears2. 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 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 will be thrown if you try to check off a box while there are unchecked boxes above it.

The following commands work with checkboxes:

C-c C-c     (org-toggle-checkbox)
Toggle checkbox status or (with prefix arg) checkbox presence at point. With a single prefix argument, add an empty checkbox or remove the current one3. 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 arg) checkbox presence at point. With double prefix argument, set it to ‘[-]’, which is considered to be an intermediate state.
M-S-<RET>     (org-insert-todo-heading)
Insert a new item with a checkbox. This works only if the cursor 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 the variable 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.

Footnotes

[1] With the exception of description lists. But you can allow it by modifying org-list-automatic-rules accordingly.

[2] Set the variable org-hierarchical-checkbox-statistics if you want such cookies to count all checkboxes below the cookie, not just those belonging to direct children.

[3] C-u C-c C-c on the first item of a list with no checkbox will add checkboxes to the rest of the list.