Checkboxes in Markdown Tables

Why doesn’t [x] render in a table cell?

A task-list checkbox is a feature of list items: GFM only turns [ ] into a checkbox when it starts a list item (- [ ] …). A table cell holds a single line of inline content and can't contain a list, so the brackets stay as typed:

| Task       | Done |
| ---------- | :--: |
| Write docs | [x]  |
| Add tests  | [ ]  |

The fix depends on where the table is read. For a README or anything on GitHub, use a character that looks like a check mark. For GitLab, the native syntax now works. For Obsidian, a plugin can help.

What to use instead: every option

Check marks with emoji and Unicode

A feature or support matrix is the most common “checkbox table”. Emoji work on every platform and in chat apps, and centering the columns with :---: keeps the marks in a straight line:

| Feature         | Free | Pro | Enterprise |
| :-------------- | :--: | :-: | :--------: |
| Unlimited repos | ✅   | ✅  | ✅         |
| SSO             | ❌   | ⚠️  | ✅         |
| Audit log       | ❌   | ❌  | ✅         |

For a step-by-step checklist, ballot-box characters read more like a form:

| Step              | Status |
| :---------------- | :----: |
| Back up database  | ☑      |
| Run migration     | ☑      |
| Verify checksums  | ☐      |
| Switch traffic    | ☐      |

On GitHub and GitLab you can keep the source ASCII with emoji shortcodes. They render as the emoji; other renderers show the :code: as text.

| Check          | Result               |
| -------------- | -------------------- |
| Lint           | :white_check_mark: Pass |
| Unit tests     | :x: Fail             |
| Coverage ≥ 80% | :heavy_check_mark: Pass |

Numeric character references produce the same ballot boxes without pasting symbols:

| Item     | Done     |
| -------- | :------: |
| Invoice  | ☑ |
| Receipt  | ☐ |

Screen readers announce emoji by name (“white heavy check mark”), so a lone icon is understandable but verbose. When the table is important, add a word: “✅ Yes”, “❌ No”. Avoid telling states apart by color alone, for example 🟩 versus 🟥.

GitLab: native checkboxes in cells

GitLab 18.9 added checkboxes in table cells. As of October 2026, GitLab's Markdown docs say [x], [ ] and [~] render as checkboxes when the checkbox is the only content of the cell. [~] is GitLab's “not applicable” state, shown struck through in task lists.

| Release step     | Done |
| ---------------- | :--: |
| Update changelog | [x]  |
| Tag the release  | [ ]  |
| Notify mirrors   | [~]  |

Anything else in the cell turns it back into text, so keep notes in a separate column. Self-managed instances on older versions show the brackets literally; the GitLab tables guide covers other GitLab-only table features.

| Release step     | Done          |
| ---------------- | ------------- |
| Update changelog | [x] by @ada   |

Obsidian: checkboxes in tables

Obsidian follows GFM here: [ ] in a cell is text in both Live Preview and Reading view. You have three options:

• Use symbols (✅ ⬜ or ☑ ☐). They look the same in every view, in exports and on publish, but you toggle them by editing the text.
• Install a community plugin. “Table Checkboxes” renders [ ] and [x] in cells as checkboxes. Like any plugin, it only applies inside your vault; the raw file still contains brackets.
• Keep the checklist outside the table as a normal task list, which Obsidian toggles and the Tasks plugin can query.

More on Obsidian's table quirks, such as escaping the pipe in wikilink aliases, is in the Obsidian and Notion guide.

HTML checkboxes where HTML is allowed

On renderers that pass raw HTML through (VS Code preview, MkDocs, Jekyll, Hugo with unsafe on, Pandoc HTML output), a real checkbox input works. Add disabled so readers don't think clicking it saves anything:

| Task       | Done |
| ---------- | :--: |
| Write docs | <input type="checkbox" disabled checked> |
| Add tests  | <input type="checkbox" disabled> |

The state lives in the source: to tick a box, add checked. If the page has to work on GitHub too, use symbols instead.

Checkbox support by platform

Common mistakes and fixes

Adding a list marker

- [x] in a cell doesn't start a list; you just get a hyphen and brackets.

| Task       | Done   |
| ---------- | ------ |
| Write docs | - [x]  |

Wrapping it in an HTML list

<ul><li> works in GitHub cells, but the task-list feature isn't applied to HTML lists, so the brackets still show.

| Task       | Done                     |
| ---------- | ------------------------ |
| Write docs | <ul><li>[x] done</li></ul> |

Extra text next to a GitLab checkbox

GitLab only converts a cell that contains nothing but the checkbox. Move comments, names and dates to their own column.

Ragged check marks

Left-aligned icons in a wide column look scattered. Center the column with :---: (see column alignment) and use the same icon set throughout. Mixing ✔ and ✅ renders at different sizes and colors.

When a table is the wrong tool

If people need to tick items off, a table is the wrong container on GitHub. Use a task list, which GitHub renders as real checkboxes and, in issues and pull requests, lets people toggle:

### Release checklist

- [x] Update changelog
- [x] Tag the release
- [ ] Publish to npm

Keep the table when you're comparing items across several columns, and use symbols for the state. For the rest of the cell rules, see Markdown table syntax; for colored status labels, see text formatting and color and badges.

Frequently asked questions