We have a new documentation site. Please go here to see the latest.

Display checklist on Create/Transition screen

Jira does not allow to show third-party elements on the Issue Create and Transition screens but you can work-around it and show Checklist Text custom field.

On this page

Prerequisites

Save checklist data to Jira custom fields option is enabled in the Issue Checklist Global Settings.

Add "Checklist Text" custom field to "Create" or "Transition" screen

 Click here to read detailed instruction...

In order to add a field to the screen in the Jira classic project, please follow the steps:

  • Go to the selected project page and select Project Settings option in the sidebar navigation:



  • Next, select Screens in sidebar navigation:



  • On the Screens page, click a name of a screen that you want to configure (depending on the operation and issue type), e.g. a screen for Create issue or View issue operation:

    You can also see the list of all screens available in Jira by going to Jira Settings > Issues > Screens page.

  • On the Configure Screen page add a field (e.g., Checklist Text) to the list:



  • Test your setup: go to the Create Issue (or View Issue) page and spot the custom field available, e.g.:

     

Example usage

When the Checklist Text custom field is present on the Create/Transition screen, you can add checklist content in the text format and get and the final checklist on the Issue View page:

 

Blocking transition

If you show the Checklist Text custom field on the transition screen and want to block transition depending on that field value, please use Regular Expression validator as it works directly with the custom field. 

The standard/built-in validator will not block the transition with the custom field modified in the transition (that is because the custom field integration is asynchronous and is synced with the real checklist after the transition is finished). 

Text format

Line beginning

In general, every new line is a separate checklist item, unless it starts with:

  • >> for description, or
  • # for the name of the checklist in the Checklist Text custom field, for example: # Default checklist

Making a list

Checklist item line can start directly with item text or Markdown characters like the following: * - + []

Examples

Unchecked items

Following is a list of six valid unchecked items (each with text/summary "checklist item").

As you can see, various prefixes are accepted to indicate the checklist item (e.g. [], *, -, but no prefix works fine too). 

In this simple form, each line is translated into a separate checklist item. 

Unchecked items
checklist item
[] checklist item
* checklist item
* [] checklist item
- checklist item
- [] checklist item

Optional and mandatory items

Following is a list of valid optional items (each with text/summary "checked item"). Question mark is used to mark item optional.

Optional items
? checklist item
[]? checklist item
*? checklist item
* []? checklist item
-? checklist item
- []? checklist item

Following is a list of four items, two of which are mandatory and two others are optional:

Checked items
[] mandatory checklist item (not completed)
[x] mandatory checklist item (completed)
[]? optional checklist item (not completed)
[x]? optional checklist item (completed)

Checked items

Following is a list of three valid checked items (each with text/summary "checklist item"):

Checked items
[x] checklist item
* [x] checklist item
- [x] checklist item

Separators (headers)

Following is a list of three valid items and one header at the beginning (headers start with three dashes "—") containing some advanced formatting elements:

Formatting
--- Acceptance Criteria
- checklist item 1
- checklist item 2 with **bold** text
- checklist item 3 with link to an issue IC-245

Description

Following is a list of two items of which the first contains additional details in description:

Item description
[] Unchecked checklist item with description
>> Details for the item above come here. Description text can be long and multiline. It can also contain links, mentions, dates, and other formatting elements. 
[x] Checked item

Statuses

Following is the list of items with different statuses (as defined in your Jira settings):

Item status
[] Open item
[open] Another open item
[in progress] Item with status 'in progress' which is still unchecked 
[done] Completed/checked item with status 'done'
[skipped] Completed/checked item with status 'skipped'

Advanced formatting

Items can consist not only of plain text, but also advanced formatting elements like description, markdown, inline code, user mention, due dates, issue keys that will be automatically linked to issues, etc.

Editor

You can examine the text format of the checklist in the editor.