ToDo List

ToDo List is a checklist field. Users fill it in on the issue: add items, tick them off, give them a status, an assignee, a due date and a note, and mark the ones that must be done. Unlike the calculated fields, it is editable.

Create it like any custom field (Jira settings → Issues → Custom fields, type ToDo List), give it a context and add it to your screens. A site can have several ToDo List fields — for example, one for a definition of done and one for a release checklist.


What an item has

Property Details
Text 1 to 255 characters. Two items of one checklist cannot have the same text (section headers can).
Status One of the statuses of the field context. Default statuses: To do, In progress, Done, Skipped.
Done checkbox Ticks the item into a status that counts as done (Done by default).
Mandatory A mandatory item must be resolved before the workflow validator lets the issue through a transition.
Assignee A Jira user, picked by name.
Due date A date. An open item past its due date is marked Overdue.
Note Free text up to 500 characters, for context, a link or an instruction.
Section header An item that starts with # becomes a section header: it groups the items below it and is not counted as work.

A checklist holds up to 100 items.

An item is resolved when its status counts as done. With the default statuses, Done and Skipped both count as done. Progress (N of M done) counts resolved items out of all items, section headers excluded.


Where users see it

On the issue

In the issue details, the field shows the checklist itself:

  • the progress line, for example 3 of 5 done, with a green progress bar;
  • every item in its order, with a checkbox mark — ticked for a resolved item, empty for an open one. The text of a resolved item is struck through. A long item wraps next to its mark, and what follows the text — lozenges, the assignee, the due date — comes after it;
  • next to each item: a Mandatory lozenge for a mandatory item; the status as a lozenge when the checkbox mark cannot say it — In progress, Skipped or a status of your own, not the first status or the first one that counts as done; the assignee’s name; the due date as a lozenge (Due 2026-07-31, or a red Overdue 2026-07-31 for an open item past its date); and a note icon that shows the note on hover;
  • section headers in bold, without a mark; they are not counted in the progress.

An empty checklist shows No items yet. The view is read-only: click the field to open the editor.

Jira does not always give the field its context’s status list. When it does not, the field still ticks each item as the checklist was saved, but shows no lozenge for a status of your own — it never shows a status’s internal id instead of its name; the ToDo List panel shows that lozenge. An assignee whose name cannot be looked up is left out rather than shown as an account id.

Which items are resolved is the same decision as everywhere else: the statuses of the field’s context, as they were when the checklist was saved.

The field and the ToDo List panel count progress the same way, including with the context’s own statuses: for one checklist they always show the same number of resolved items.

In the issue history, the issue navigator, on board cards, in email notifications and in exports, the field shows one line: progress as done/total, then every item with its mark — for example 1/2 · [x] Run regression tests; [ ] Update release notes. [x] is the status a tick sets, [ ] the status a new item starts in, any other status is shown by name ([In progress], [Skipped]); section headers appear as they are. Assignees, notes and due dates are not in the line. The line is at most 255 characters: for a longer checklist, section headers are left out, the items the save changed come first and the rest are counted as +N more. Nothing is shown when the checklist is empty. A checklist last saved before this line existed shows only done/total until it is saved again.

The ToDo List panel (see below) shows the same checklist with more room, and every ToDo List field of the issue in one place. It reads the same as the field: the same progress line and green bar, the same Mandatory and status lozenges, the same assignee names and due-date lozenges, the same No items yet. for an empty checklist.

Editing

The editor opens on the issue view, on the create screen and on transition screens.

Each item is one row: the drag handle and the done checkbox on the left, the text next to them, and under the text the item’s status, assignee and due date — all in one compact size. The item’s actions — the star (Optional item / Mandatory item), the note (Add a note), Move up, Move down and Delete item — are icons at the end of the text line; they show up when the pointer is over the item or the keyboard focus is in it, and every icon names its action on hover. A star that is on and a note that exists stay visible all the time.

  • Add an item: type in “Add an item — start with “# “ for a section header” and press Enter.
  • Paste a checklist: paste a markdown list into the add box to import it in one go. Bullets (-, *, +, 1.), checkboxes ([ ], [x]) and headings (# … ######) are understood; a checked box becomes a done item, a heading becomes a section header. Lines over the 100-item limit are not added, and the editor says how many were dropped.
  • Edit text: click the text; Enter saves, Esc cancels.
  • Reorder: drag an item by its handle, or use Move up / Move down.
  • Delete: Delete item, then confirm.
  • Save stores the checklist; Cancel discards the changes. If something must be fixed first, the editor lists it under “Fix these before saving”.

When the field is empty and its context has default items, the editor starts from them: “Prefilled from the field configuration. Nothing is stored until you save.”

ToDo List issue panel

The ToDo List panel shows every ToDo List field that applies to the issue in one place, with more room than the field slot. Open it from the issue’s View app actions menu → ToDo List.

The first time a user opens the panel, Jira may ask them to grant the app access (“For ToDo List to display, you need to grant it access to Atlassian apps on your behalf.”). After Allow access, the panel loads.

  • With one ToDo List field on the issue, the checklist starts right under the panel’s ToDo List title, with its progress first. With several, each field is shown under its own name.
  • Each field is shown with its progress. Tick an item’s checkbox to mark it done, or clear it to reopen the item — straight in the list, without Edit. The progress updates once the change is saved; if it cannot be saved, the checkbox goes back and the panel says why (“Could not update the item: …”).
  • A tick changes only that item: items other people added or changed while the panel was open are kept.
  • An item can be ticked right after Save: the panel waits a few seconds for Jira to return the saved checklist rather than reporting the item as removed. An item someone really removed is reported as “This item is no longer on the checklist — someone may have removed it.”, and the list shows what Jira holds.
  • In a field with its own statuses, a tick moves the item to the first status that counts as done, and clearing it moves the item to the first status that does not. Other statuses are set through Edit.
  • Edit opens the same editor as the field, for text, order, assignees, due dates, notes and statuses.
  • Edit and the checkboxes work only for users who can edit the issue; for others the checkboxes are shown but disabled (“You need permission to edit this issue to tick items.”).
  • “No ToDo List field is set up on this site yet. An admin can add one in Jira’s custom-field settings.” — the site has no ToDo List field.
  • “No ToDo List field applies to this issue. An admin can add the field to this project’s context.” — the fields exist but their contexts do not cover this issue.

The panel and the field edit the same value: there is no second copy. Saving from the field or from the panel, and ticking an item in the panel, adds an entry to the issue history in the name of the user who did it, showing the checklist before and after as the one line described above. If Jira does not allow the user to edit the issue, the panel saves nothing and says why, as Jira does for its own fields — for example “This issue can’t be edited in its current status.” for an issue in a workflow status that locks editing, “You don’t have permission to edit this issue.”, or “Someone changed this issue at the same time. Reload the issue and try again.”; a tick goes back, and an edit returns to the saved checklist. If the user has not yet given the app access on their behalf, the panel asks them to select Allow access and try again, and the editor keeps their changes. Only when Jira cannot be reached or fails on its side does the app store the checklist itself, and that history entry names the app. A checklist template applied on create and the removal of closed accounts (see Personal data) are recorded in the app’s name.


Field context settings

Open the configuration of the field context. The settings apply to every issue the context covers (“These settings apply to every issue this field context covers.”). The settings that apply to an issue are those of the context that covers it: a project context wins over the global context.

Setting Default Effect
Allow adding new items On When off, users can only work through the items that are already on the checklist.
Allow editing and deleting default items On When off, users can still tick and re-status the default items, but not rename or remove them. Locked items show “Default item — locked by the field configuration”.
Default items None An empty checklist starts from these items. Each has a text, an initial status, Mandatory and Section header. Nothing is stored on an issue until somebody saves the field there.
Statuses To do, In progress, Done, Skipped The statuses an item can be set to.

Statuses

Each status has a name (up to 40 characters), a colour (Grey, Blue, Green, Red, Yellow or Purple) and Counts as done.

  • Counts as done is what closes an item: it ticks the checkbox, fills the progress bar and satisfies allItemsDone() in JQL. The set must have at least one status that counts as done.
  • The first status of the set is the one new items get, and the one allItemsUndone() treats as “not started”.
  • Add a status by typing its name in Add a status and pressing Enter or Add status; default items are added the same way with Add item.
  • A context can have up to 8 statuses. Reorder them with Move status up / Move status down.
  • Reset to the default statuses brings back To do, In progress, Done, Skipped.
  • Each status keeps a stable id (shown as “id: …” under its name): renaming a status does not change the items that have it, and JQL searches by this id.

Limits

Limit Value
Items per checklist 100
Item text 255 characters
Item note 500 characters
Statuses per field context 8
Status name 40 characters