# How to Create Interactive Task Lists in GitHub Issues and Pull Requests > Learn to create interactive task lists in GitHub issues and pull requests. GitHub Markdown checkboxes let you track progress effortlessly. Boost your workflow today. - Repository: [Tim Green/github-cheat-sheet](https://github.com/tiimgreen/github-cheat-sheet) - Tags: how-to-guide - Published: 2026-03-06 --- **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`](https://github.com/tiimgreen/github-cheat-sheet/blob/main/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](https://github.com/tiimgreen/github-cheat-sheet/blob/master/README.md#task-lists-in-markdown-documents) section of the cheat sheet, files like [`README.md`](https://github.com/tiimgreen/github-cheat-sheet/blob/main/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: ```markdown - [ ] Write unit tests - [ ] Update documentation - [ ] Merge feature branch ``` After a user clicks "Write unit tests," GitHub automatically updates the source to: ```markdown - [x] Write unit tests - [ ] Update documentation - [ ] Merge feature branch ``` See the [basic example in README.md](https://github.com/tiimgreen/github-cheat-sheet/blob/master/README.md#L28-L34) 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: ```markdown ## Review checklist - [ ] Verify code follows style guide - [ ] Run integration tests - [ ] Local environment - [ ] CI pipeline - [ ] Check changelog entry ``` The [nested example](https://github.com/tiimgreen/github-cheat-sheet/blob/master/README.md#L35-L38) 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: ```markdown - [ ] @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: ```markdown - [ ] 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](https://github.com/tiimgreen/github-cheat-sheet/blob/master/README.md#task-lists-in-markdown-documents). ## 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`](https://github.com/tiimgreen/github-cheat-sheet/blob/main/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`](https://github.com/tiimgreen/github-cheat-sheet/blob/main/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.