How to Create Interactive Task Lists in GitHub Issues and Pull Requests

GitHub renders Markdown checkboxes as clickable UI elements in issues and pull requests, automatically persisting state changes to the underlying - [ ] or - [x] syntax when users click them.

You can turn any GitHub issue, pull request description, or comment into a dynamic project tracker using GitHub-flavored Markdown syntax. According to the tiimgreen/github-cheat-sheet repository, this feature requires no special permissions or external tools—just specific characters in your Markdown source.

GitHub-Flavored Markdown Syntax for Task Lists

Interactive task lists use a hyphen-bracket pattern that GitHub parses into HTML checkboxes.

• Unchecked items: Write - [ ] followed by a space and your text
• Checked items: Write - [x] or - [X] (lowercase or uppercase) inside the brackets

When rendered in mutable contexts, each checkbox becomes a clickable form element. Clicking a box triggers a background update where GitHub rewrites the Markdown source—converting - [ ] to - [x] or vice versa—and commits the change to the repository's data store. This persistence happens without requiring users to manually edit the raw Markdown.

Where Interactive Task Lists Work (and Where They Don't)

The interactivity of checkboxes depends entirely on whether the Markdown content is editable.

Mutable contexts (fully interactive):

• Issue bodies and comments
• Pull request descriptions
• Any comment thread within the repository

Read-only contexts (static display only):

• README.md files rendered on repository main pages
• Any committed Markdown file viewed in the file browser

As documented in the Task Lists in Markdown Documents section of the cheat sheet, files like README.md display checkboxes as disabled UI elements because the underlying file content cannot be modified through the web interface. The visual syntax renders correctly, but users cannot toggle the state.

Practical Implementation Examples

The tiimgreen/github-cheat-sheet repository provides concrete patterns for implementing task lists in different scenarios.

Basic Checklist in an Issue

Create a simple to-do list by placing each task on its own line with the checkbox syntax:

- [ ] Write unit tests
- [ ] Update documentation
- [ ] Merge feature branch

After a user clicks "Write unit tests," GitHub automatically updates the source to:

- [x] Write unit tests
- [ ] Update documentation
- [ ] Merge feature branch

See the basic example in README.md for the rendered output.

Nested Task Lists for Complex Workflows

Task lists support arbitrary nesting through indentation, making them suitable for hierarchical project management. Each sub-item maintains its own independent checkbox state:

## Review checklist

- [ ] Verify code follows style guide
- [ ] Run integration tests
  - [ ] Local environment
  - [ ] CI pipeline
- [ ] Check changelog entry

The nested example demonstrates that indentation preserves the parent-child relationship while allowing independent state toggling for each level.

Task Assignment with User Mentions

Combine task lists with GitHub mentions (@username) to create accountability directly within the thread:

- [ ] @alice Update API client
- [ ] @bob Refactor auth middleware
- [ ] @carol Add end-to-end tests

Each assignee can check off their specific item when complete, providing clear ownership tracking without external project management tools.

Static Checklists in Documentation

When documenting project status or feature roadmaps in read-only files, use the same syntax knowing the boxes will render as static indicators:

- [ ] Mercury
- [x] Venus
- [x] Earth
  - [x] Moon
- [x] Mars
  - [ ] Deimos
  - [ ] Phobos

This displays completion status visually but prevents interaction, as noted in the read-only documentation.

Summary

• Use - [ ] for unchecked and - [x] for checked items in GitHub-flavored Markdown
• Interactive toggling only works in editable contexts: issues, pull requests, and comments
• GitHub automatically persists checkbox state changes by rewriting the underlying Markdown source on the server
• Nested task lists support complex workflows with hierarchical indentation
• Files like README.md display static checkboxes that cannot be toggled through the web interface

Frequently Asked Questions

Can I use interactive task lists in README files?

No. Checkboxes in committed files like README.md render as static, non-clickable elements. The interactive functionality requires a mutable context such as an issue comment or pull request description where GitHub has permission to modify the underlying Markdown source.

How does GitHub persist checkbox state changes?

When you click a checkbox in an issue or PR, GitHub's backend rewrites the Markdown from - [ ] to - [x] (or vice versa) and updates the stored comment body. You can verify this by clicking "Edit" on the comment—the raw Markdown reflects the current checked state.

Are nested checkboxes supported?

Yes. You can indent task list items with spaces to create parent-child relationships. Each nested checkbox maintains independent state, allowing you to complete sub-tasks without automatically marking parent tasks as complete.

Can I track task completion statistics across my repository?

GitHub provides a progress indicator in the issue/PR list view showing "2 of 5 tasks complete" based on the ratio of checked to unchecked boxes in the first comment. However, detailed analytics require third-party tools or the GitHub API to parse task list states programmatically.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}