Documentation for JIRA 4.0. Documentation for other versions of JIRA is available too.

Skip to end of metadata
Go to start of metadata

On this page:

Custom Fields Overview

Custom field types were introduced in JIRA 2.0 to allow greater customisability of the types of data collected with your issue. In 3.0, the number types have been expanded and you can even add your own custom field types. JIRA 3.2 adds a new level of flexibility to your custom fields. You can now configure your custom fields to only appear for certain issue types in certain projects or multiple issue types over multiple projects. On top of that, you can even configure each custom field differently for each context

This page outlines some of the key concepts relating to custom fields.

To build your own custom field types, check out the tutorial at the JIRA Development Hub.


Custom fields are always optional fields. This means you can add custom fields without requiring existing issues to be changed. The current issues contain no value for the custom field, even if a default is defined.

Custom Field Types

JIRA now ships with over 20 custom field types and you can find more custom field types and other examples in the JIRA Extensions space (e.g. JIRA Toolkit). A sample of the types are listed below.

Custom Field Type


Cascading Select

Multiple select lists where the options for the second select list dynamically updates based on the value of the first

Date Picker

Input field allowing input with a date picker and enforcing valid dates

Date Time

A custom field that stores dates with a time component.

Free Text Field (unlimited text)

Multiple line text-area enabling entry of longer text strings

Multi Checkboxes

Checkboxes allowing multiple values to be selected

Multi Select

Select list permitting multiple values to be selected

Number Field

Input field storing and validating numeric (floating point) values

Project Picker

Select list displaying the projects viewable by the user in the system

Radio Buttons

Radio buttons ensuring only one value can be selected

Select List

Single select list with a configurable list of options

Text Field

Basic single line input field to allow simple text input of less than 255 characters

URL Field

Input field that validates a valid URL

User Picker

Choose a user from the user base via a popup picker window.

Multi User Picker

Choose one or more users from the user base via a popup picker window.

Group Picker

Choose a user group using a popup picker window.

Multi Group Picker

Choose one or more user groups using a popup picker window.

Single Version Picker

Choose a single version from available versions in the project.

Version Picker

Choose one or more versions from available versions in the project.

Search templates

Search templates are responsible for indexing a custom field as well as making it searchable through the Issue Navigator (note that custom fields are not searchable via QuickSearch ). Each of the default custom field types has a related pre-configured search template.

Custom field context

The custom field context (introduced in JIRA 3.2) allows your custom field to be configured (that is, enabled) for any numerous different combinations of issue types and projects. You can have different default values in different projects, different options for different projects and the like.

The context is made up of an issue type component and a project component. You can select multiple issue types and multiple projects or declare the custom field to be global.

The context itself can now be modified at any time. You can change the project or issue type applicable for the custom field at any time.

Custom field configuration schemes

If you start digging deeper into custom fields (or indeed, any part of JIRA) you'll notice many references to schemes. Custom field configuration schemes are how JIRA allow you to manage custom field contexts and configuration. A configuration scheme is configuration set for a group of issue types for a set of projects. If you have two different default values, you'd need two configuration schemes and so on.

Specific project based configuration schemes will override configurations from a Global project context. So you could configure a default global scheme for all projects and the configure for each projects that are different. You may for example, have a global select lists that have values that applies for 80 of your 81 projects but is different in the other. You'd configure a one configuration scheme for global context and other for the specific field that is different.

Also note that to avoid conflicts, a project can only be part of a single configuration scheme. Once you've selected a specific project to be part of a scheme, it will be removed from the list of selectable options

Adding a Custom Field

Steps to define a custom field

  1. Log in as a user with the ' JIRA Administrators ' global permission .
  2. Bring up the administration page by clicking either the ' Administration ' link on the top bar or the title of the Administration box on the dashboard:
  3. On the menu bar on the left, under "Issue Fields" sub-menu click the Custom Fields link, and then click on the Add Custom Field link on the presented page.
  4. Select from the list the appropriate custom field type.
  5. Click on the next button.
  6. Fill in the Field Name and Field Description. The Field Name will appear as the custom field's title in both entering and retrieving information on issues. The Field Description is displayed beneath the data entry field when entering new issues and editing existing issues, but not when browsing issues.
  7. Select an appropriate Search Template. Pre-configured search templates are available for each shipped custom field type. A description of each search template will appear next to the select list when you select one.
  8. Select one or any number of issue types that this custom field will be applicable for. You can change this value in the future if you need to.
  9. Select the applicable project context. The custom field will be available to the selected projects. If issue types were chosen, it will only appear for those issue types for that project
  10. Click Finish.
  11. This will bring you to the screen association page where you can put your newly created custom field onto a screen in JIRA. You can associate the field any screens or tabs in JIRA. You must associate a field to a screen before it will be displayed. New fields will be added to the end of a tab.
  12. Clicking Update will return you to the View Custom Fields page that displays a summary of the custom fields in the system. You can edit, delete or configure custom fields here. This page is also directly accessible from the menu bar to the left of all Administration pages.

Additional Resources

  • Adding a custom field tutorial video - Watch this short tutorial video to see how to add and configure a new custom field. Please note the JIRA version and JIRA edition of the tutorial video before watching.