Markdown Checkbox

Basic Checkbox Syntax

A Markdown checkbox is a list item that starts with - [ ] (unchecked) or - [x] (checked). The space inside the brackets is required for an unchecked box. You can also use * or + instead of - as the list marker.

- [ ] Buy groceries
- [x] Write documentation
- [ ] Review pull request

The syntax is strict: - [ ] needs exactly one space between the brackets for an unchecked box. - [x] uses a lowercase x. Some processors also accept [X] (uppercase), but lowercase is the standard.

- [ ] task       <-- unchecked checkbox
- [x] task       <-- checked checkbox
- [] task        <-- not a checkbox (no space inside brackets)
-[ ] task        <-- not a checkbox (no space after dash)

Nested Task Lists

Indent sub-tasks with two or four spaces to create nested checklists. Each level of indentation creates a deeper nesting. This is useful for breaking down a large task into smaller steps.

- [x] Set up project
  - [x] Initialize repository
  - [x] Add .gitignore
  - [ ] Configure CI
- [ ] Write tests
  - [ ] Unit tests
  - [ ] Integration tests
- [ ] Deploy to production

Most processors accept two-space indentation. GitHub and GitLab both support nested task lists with two or four spaces. If your sub-tasks are not rendering as nested, try switching between two and four spaces.

Interactive Checkboxes

On GitHub, checkboxes in issues and pull request descriptions are interactive. You can click them to toggle between checked and unchecked, and GitHub updates the underlying Markdown source automatically. This makes task lists a practical tool for tracking progress directly from the issue page.

- [x] Design database schema
- [x] Implement API endpoints
- [ ] Add authentication
- [ ] Write API documentation

GitHub also shows a progress bar on issues with task lists, displaying the fraction of completed tasks. Other apps with interactive checkboxes include Obsidian, MDViewer, and some GitLab views. In a plain text editor, you toggle by changing [ ] to [x] manually.

Checkbox in Pull Requests

Task lists are widely used in pull request templates to ensure reviewers and authors follow a checklist before merging. GitHub renders these as interactive checkboxes in the PR description.

### Pre-merge checklist

- [x] Code follows the style guide
- [x] Tests pass locally
- [ ] Documentation updated
- [ ] Reviewed by at least one team member
- [ ] No console errors in the browser

To add a task list to your PR template, create a file at .github/PULL_REQUEST_TEMPLATE.md in your repository with the checklist content. GitHub will auto-populate every new PR with this template.

Checkbox with Other Formatting

You can combine checkbox syntax with bold, italic, links, and strikethrough. This is useful for emphasizing important tasks or marking completed items with a visual cue.

Bold and italic task text

- [ ] **Critical:** Fix security vulnerability
- [ ] *Optional:* Update color scheme
- [x] ***Urgent:*** Patch production server

Links in task items

- [x] Review [issue #42](https://github.com/org/repo/issues/42)
- [ ] Update [README.md](README.md)

Strikethrough for completed tasks

- [x] ~~Set up database~~
- [x] ~~Create user model~~
- [ ] Implement login flow

Checkbox in Tables

Task list syntax (- [ ]) does not work inside Markdown table cells because table cells do not support list items. As a workaround, you can use emoji or Unicode characters to indicate checked and unchecked states.

| Task               | Status      | Assignee |
|--------------------|-------------|----------|
| Database migration | ☑ Done    | Alice    |
| API endpoints      | ☑ Done    | Bob      |
| Frontend forms     | ☐ Pending | Carol    |
| Load testing       | ☐ Pending | Dave     |

The Unicode characters ☐ (☐ empty ballot box) and ☑ (☑ checked ballot box) render on most platforms. You can also use plain-text markers like [x] and [ ] as cell text, though they will not render as actual checkboxes.

GFM Extension

Task lists are not part of the original Markdown specification by John Gruber, nor are they part of the CommonMark standard. They are a GitHub Flavored Markdown (GFM) extension, first introduced by GitHub and later adopted by many other platforms.

This means that a Markdown processor that only implements standard CommonMark will render - [ ] Task as a regular list item with literal brackets rather than a checkbox. Before relying on task lists, check whether your target platform supports GFM or has its own task list extension.

Standard Markdown:   - [ ] Task  →  renders as "[ ] Task" in a bullet list
GFM:                 - [ ] Task  →  renders as a checkbox

HTML Alternative

If your Markdown processor does not support GFM task lists, you can use raw HTML <input> elements. Most Markdown renderers that allow inline HTML will display these as checkboxes.

<input type="checkbox" disabled> Write the report
<input type="checkbox" disabled checked> Send the invoice
<input type="checkbox" disabled> Follow up with client

Always include the disabled attribute to prevent users from accidentally toggling the checkbox in rendered HTML (unless your platform intentionally supports interactive checkboxes). Note that some platforms like GitHub strip raw <input> tags from Markdown for security, so the GFM syntax is preferred on GitHub.

Platform Support

Task list support varies by platform. Here is how major Markdown tools handle checkbox syntax.

If your target platform is listed as "No" for task lists, use the HTML alternative or plain-text markers like [x] and [ ] as visual indicators.

Common Use Cases

Todo lists in project READMEs

## Roadmap

- [x] User authentication
- [x] REST API
- [ ] GraphQL support
- [ ] Mobile app

Meeting notes with action items

### Action items — Oct 7 standup

- [ ] @alice: Update staging environment
- [ ] @bob: Fix login page CSS
- [x] @carol: Merge feature branch

Documentation review checklist

- [ ] All code examples tested
- [ ] Links are not broken
- [ ] Spelling and grammar checked
- [ ] Screenshots are up to date
- [ ] Version numbers are correct

Render Task Lists with MDViewer

MDViewer is a native macOS app that renders GitHub Flavored Markdown, including interactive task lists with clickable checkboxes. Open any .md file in Finder and see your checklists rendered with real checkboxes — toggle them directly in the preview. Lite is free; Pro adds editing, Git history, and PDF export.

Requires macOS 13.0 or later. Intel and Apple Silicon.

FAQ

How do I create a checkbox in Markdown?

Start a list item with a dash, a space, and square brackets: - [ ] for an unchecked box and - [x] for a checked box. The space inside the brackets is required. This syntax is part of GitHub Flavored Markdown (GFM) and works on GitHub, GitLab, VS Code, Obsidian, and MDViewer.

Can I click Markdown checkboxes?

On GitHub, checkboxes in issues and pull requests are interactive — you can click them to toggle the state, and GitHub updates the underlying Markdown automatically. Obsidian and MDViewer also support clickable checkboxes. In a plain text editor, you need to change [ ] to [x] manually.

Do Markdown checkboxes work everywhere?

No. Task list checkboxes are a GFM extension, not part of standard Markdown or CommonMark. They work on GitHub, GitLab, VS Code preview, Obsidian, MDViewer, and most modern Markdown apps. They do not work on platforms that only support basic Markdown, such as Slack, Discord, or Reddit.

How do I create a nested task list?

Indent sub-tasks with two or four spaces before the dash. For example, write - [x] Main task on the first line, then   - [ ] Sub-task indented on the next line. Each level of indentation creates a deeper nesting level.

What's the HTML alternative for Markdown checkboxes?

Use the HTML input element: <input type="checkbox" disabled> for unchecked and <input type="checkbox" disabled checked> for checked. The disabled attribute prevents interaction. This works on any platform that allows inline HTML in Markdown, even without GFM support.