Skip to main content

Markdown Checkbox

How to make checkboxes and task lists in Markdown, where you can actually click them, and what to do in tables, numbered lists, and apps that do not support them.

Short answer

Write a list item with brackets: - [ ] To do for an empty box, - [x] Done for a checked one. This is a GitHub Flavored Markdown extension, not core Markdown. On GitHub the boxes are clickable in issues, pull requests, and comments, but read-only in a README or any other .md file.

Basic Syntax

A checkbox is a list item whose text starts with a bracket pair. The pieces are: list marker, space, [, one character, ], space, then the task text.

Simple task list
- [ ] Buy groceries
- [x] Walk the dog
- [ ] Write the changelog
Preview
Separate lists under headings
### Today
- [x] Check metrics
- [ ] Reply to blocked PRs

### This week
- [ ] Interview candidates
Preview

Each heading ends the list above it, so you get one checklist per section.

Checked vs Unchecked

A space inside the brackets is unchecked. An x is checked, and the GFM spec accepts an uppercase X as well. Anything else, including an empty pair or extra spaces, is not a checkbox at all.

x, X, and space
- [x] Lowercase x
- [X] Uppercase X
- [ ] Unchecked
Preview

Nested and Numbered Tasks

Indent a sub-task so its marker lines up with the parent's text: 2 spaces under a - item, 3 under a 1. item. The full rule is in the nested lists guide.

Nested checklist
- [ ] Ship v2.0
  - [x] Finalize API
  - [x] Write docs
  - [ ] Update screenshots
- [ ] Announce release
Preview
Numbered task list
1. [x] Back up the database
2. [ ] Run the migration
3. [ ] Notify the team
Preview

The GFM spec defines task items on any list item, so numbered checklists render on GitHub and GitLab too.

Clickable Checkboxes on GitHub

Where you write the task list on GitHub decides whether people can tick it.

WhereCheckboxes
Issue or pull request descriptionClickable. Progress (for example 1 of 3) shows in the repository's issue list.
Comments and discussionsClickable. Clicking rewrites the [ ] or [x] in the comment for you.
README and other .md filesRead-only. Edit the file to change a box.
Pull request checklist
## Before merging
- [ ] Tests pass locally
- [ ] Docs updated
- [ ] \(Optional) Screenshot attached
Preview (read-only here; clickable in a GitHub PR)

GitHub's docs say to escape a parenthesis that starts the task text, as in \(Optional).

Tasklist blocks are gone, task lists are not. GitHub retired its ```[tasklist] preview feature on April 30, 2025 and points people to sub-issues instead. Plain - [ ] task lists were never part of that and still work.

Checkboxes in Tables, and Literal Brackets

Task syntax only works at the very start of a list item. Inside a table cell, [x] is just text, and GitHub's HTML allowlist does not include <input>, so a raw HTML checkbox is removed. Use a symbol.

Status column with symbols
| Task          | Done |
| ------------- | :--: |
| Write tests   |  ✅  |
| Update docs   |  ⬜  |
Preview

On GitHub you can also type :white_check_mark: and :white_large_square: shortcodes.

Escape the bracket to keep it as text
- \[ ] Not a checkbox, just brackets
- \[x] Also plain text
Preview

A backslash before [ stops the task marker from forming.

Obsidian Task States

Obsidian uses the same syntax and lets you tick boxes in Reading view. It also counts any character in the brackets as complete, which is how people build extra states. On their own these all render as checked; distinct icons come from a theme or CSS snippet, and the Tasks plugin can treat them as statuses.

Custom states (Obsidian convention)
- [x] Done
- [/] In progress
- [-] Cancelled
- [?] Question
Preview (GitHub Flavored Markdown)

On GitHub and in other GFM renderers, only [x] is a checkbox. The other three show as literal text, as in this preview.

Platform Support

Task lists need GitHub Flavored Markdown or an equivalent extension. Where they are missing, the brackets show up as text.

PlatformSupported?Notes
GitHubYesClickable in issues, pull requests, discussions, and comments. Read-only in .md files such as a README.
GitLabYesClickable in issues, merge requests, epics, and comments. Also supports [~] for an inapplicable task.
ObsidianYesClickable in Reading view. Any character in the brackets marks the task done; custom icons need a theme or CSS snippet.
VS Code previewNoThe built-in preview shows a bullet with literal [ ] / [x]. The Markdown Checkboxes or Markdown All in One extension adds checkboxes.
Docusaurus / AstroYesBoth enable GitHub Flavored Markdown by default, so task lists render as read-only checkboxes.
MkDocsPartialPython-Markdown has no task lists on its own; add the pymdownx.tasklist extension.
NotionPartialNative to-do blocks: type [] then space. Notion does not document converting pasted - [ ] lines.
SlackPartialOnly inside Block Kit markdown blocks sent by apps (added March 2026). Not in the composer or mrkdwn.
DiscordNo- [ ] renders as a bullet followed by literal brackets.
RedditNoNot part of Reddit's Markdown. The brackets show as text.
CommonMarkNoCore CommonMark renders literal [ ] text. Checkboxes come from the GFM task list extension.

Common Mistakes

A checkbox that will not render is nearly always a spacing problem inside or around the brackets.

Broken

- [] Empty task

Fixed

- [ ] Empty task
The brackets need one character inside: a space for unchecked, or x for checked. Empty brackets stay as literal text.

Broken

- [ x ] Task

Fixed

- [x] Task
Spaces around the x make it three characters, so the parser no longer sees a task marker.

Broken

- [x]Task

Fixed

- [x] Task
GFM requires whitespace after the closing bracket. Without it the line is an ordinary list item that starts with [x].

Broken

[ ] Task with no list marker

Fixed

- [ ] Task with a list marker
A checkbox only exists at the start of a list item. Without -, *, +, or a number in front, the brackets are plain paragraph text.

Broken

- [x] Item 1
  - [x] Subtask A
 - [ ] Subtask B

Fixed

- [x] Item 1
  - [x] Subtask A
  - [ ] Subtask B
Subtask B is indented 1 space, less than the 2 its parent's text needs, so it pops back out to the top level. Indent every child to the parent's text.

Quick Reference

SyntaxResultNotes
- [ ] taskUncheckedSpace inside the brackets
- [x] taskCheckedLowercase x
- [X] taskCheckedUppercase also valid in GFM
* [ ] taskUncheckedAny bullet marker works
1. [ ] taskNumbered taskValid GFM; renders on GitHub and GitLab
- [ ] taskNested task2 spaces under a - parent
- \[ ] taskLiteral [ ]Backslash escapes the bracket
- [~] taskInapplicableGitLab only
- [-] taskCustom stateObsidian themes and plugins; checked by default

Frequently Asked Questions

How do you make a checkbox in Markdown?

Start a list item, then add a pair of brackets and a space: - [ ] for an empty box or - [x] for a checked one. The brackets must hold exactly one character, and there must be a space after the closing bracket.

How do you check a box in Markdown?

Put an x between the brackets: - [x] Done. GitHub Flavored Markdown accepts lowercase x or uppercase X. To uncheck it, replace the x with a space.

Are checkboxes part of standard Markdown?

No. Task lists are a GitHub Flavored Markdown extension. GitHub, GitLab, Obsidian, and most static site generators support them (VS Code's built-in preview needs an extension), but a strict CommonMark parser shows - [ ] as a bullet with literal brackets.

Can you click Markdown checkboxes on GitHub?

Yes, in issues, pull requests, discussions, and comments. Clicking a box edits the underlying Markdown for you, and an issue's task progress shows up in places like the repository's issue list.

Why can't I check the boxes in my README?

GitHub renders task lists in Markdown files as read-only checkboxes. To change one, edit the file and swap [ ] for [x], which needs write access to the repository. Use an issue if you want boxes people can click.

Can you nest checkboxes in Markdown?

Yes. Indent the child task so its marker lines up with the parent's text, which is 2 spaces under a - item: - [ ] Parent - [ ] Child

Can I use checkboxes in a numbered list?

Yes. GitHub Flavored Markdown defines task items on any list item, so 1. [ ] Step renders a numbered checkbox on GitHub and GitLab. Use a bullet list if the file also has to render in a tool you have not tested.

How do I put a checkbox in a Markdown table?

Task list syntax only works at the start of a list item, so - [ ] inside a table cell stays as text. Use a symbol instead, such as ✅ and ⬜, or GitHub's :white_check_mark: shortcode. Raw <input type="checkbox"> HTML is not on GitHub's allowed-tag list.

How do I show [ ] without it turning into a checkbox?

Escape the opening bracket with a backslash: - \[ ] text. On GitHub, also escape an opening parenthesis right after the box, as in - [ ] \(Optional) text, which GitHub's docs call out.

Why is my Markdown checkbox not rendering?

Check for empty brackets ([]), spaces around the x ([ x ]), no space after the bracket ([x]Task), a missing list marker in front, or a platform that does not support task lists, such as Discord, Reddit, or a strict CommonMark renderer.

Does Obsidian support other checkbox states like [-] or [/]?

Obsidian treats any character inside the brackets as complete, so [-], [/], and [?] all render as checked by default. Different icons for each state come from a theme or CSS snippet, and the Tasks plugin can treat them as statuses such as In Progress or Cancelled.

Do Notion, Slack, and Discord support Markdown checkboxes?

Notion has native to-do blocks: type [] then space. Slack renders - [ ] only inside Block Kit markdown blocks that apps send. Discord does not support task lists; the brackets show as plain text.

What happened to GitHub tasklist blocks?

The ```[tasklist] code-block feature was a GitHub preview that was retired on April 30, 2025, with sub-issues as the replacement. Ordinary - [ ] task lists were not affected and still work everywhere on GitHub.