Markdown · <code>- [ ] task</code>
Task lists
GFM task lists add checkboxes to list items with [ ] and [x].
Key facts
| Unchecked | <code>- [ ] task</code> |
|---|---|
| Checked | <code>- [x] task</code> |
| Case | <code>x</code> or <code>X</code> |
| Nesting | Works inside normal lists |
| Standard | GFM extension |
Checkboxes in text
A task list is a normal list item whose text starts with [ ] or [x]. GFM renders the marker as a disabled checkbox. The box is presentational: in most renderers it is not clickable, and the source text is the only state.
Because it is just text, a task list is easy to edit in any editor and diffs cleanly in version control. That is why issue templates and pull-request descriptions use it heavily.
Limits and accessibility
The checkbox has no accessible label beyond the item text, and the state is conveyed visually. In a context where the list is the primary content, repeat the state in words or use a real form control.
Task lists are a GFM extension. Renderers without support show the brackets literally, which is ugly but still readable. Nested task lists work as long as the indentation is correct.
Frequently asked questions
Can I click the checkbox?
In GitHub's web editor, sometimes. In most Markdown renderers, no; edit the source text to change state.
Does [X] with a capital X work?
Yes. GFM accepts x or X inside the brackets.