Custom Fields in Issues

Every issue comes with a set of commonly-used default fields shown in its right-hand sidebar, such as Assignee, Due date, Status, Tag.

If your team needs additional categories for issues, you can define and add custom fields. They can be used to store values for prioritizing, scheduling, references, specifications, or whatever else your team needs for efficient work.

Custom fields can be created of different types to accommodate for specific value format, such as:

Text — to enter and store a simple line of text
Date — to set a date picked from a calender
List — to choose from a number of predefined values

and many more. For a full list and description, see Custom field types.

Create, edit, delete custom fields

Create a custom field

Open your project.
On you project sidebar, choose Issues.
On the Issues page, click the Settings button:
On the issues Settings page, go to the Issue Fields tab:
You can quickly add a preconfigured custom field (Type, Priority, or Browser). Choose it from the drop-down menu next to the New field button, review and edit the options (if necessary), then click Save:
To create a custom field from scratch, with your own settings, click the New field button and fill out the form:
Enter the field Name and select its Type. The settings and options will depend on the type you choose. For a detailed description of each setting, see Custom field settings.
Use the interactive Live preview at the bottom of the form to see and test your custom field.
When you're done, click Save. The new custom field will be added to your project issues.

Edit custom field settings

On the Issues page, click the Settings button:
On the issues Settings page, go to the Issue Fields tab:
On the Fields list, locate the field you want to edit and click next to it.
Refer to the custom fields settings and types descriptions to edit the settings.
Some settings cannot be changed in existing fields to prevent data corruption.

Delete a custom field

On the Issues page, click the Settings button:
On the issues Settings page, go to the Issue Fields tab:
On the Fields list, locate the field you want to delete and click next to it.
Click Delete.
This will delete the field from all issues. All values or data entered in this field will be deleted as well.

Custom field types

Type	Description
Text	Can be used to enter and store a short text (string of alphanumeric characters)
Number	Can store integers only.
List	A selection of predefined values (list items) that users can choose from (or add their own if the `Open-ended` option is enabled)
Checkbox	A checkbox can be used for any binary input. For example, you can provide some question in its description, and the users can answer 'yes' by selecting the checkbox.
Date	Stores a single value in a date format. Users set and change the value by picking a date from a calendar popup.
Date and Time	Stores a single value in a date/time format. Users set and change the value by picking a date and time from a calendar popup.
Percentage	Stores a single integer value (from 0 to 100 by default) and shows it along with a progress bar.
Organization member	Stores a reference to a member profile. Users can pick a member from a drop-down list.
Team	Stores a reference to one of the teams in your organization. Users can pick a team from a drop-down list.
Location	Stores a reference to one of the locations defined in your organization. Users can pick a location from a drop-down list.
Project	Stores a reference to one of the projects in your organization. Users can pick a project from a drop-down list.
Link	Can be used to provide and store a link to an internal or external resource.
Issue	Can be used to store a link to a related issue. To enter a reference to an issue, users should copy the issue ID link on the issue page and paste it into the field.
Fraction	Can store fractional numbers which users can pick from a drop-down menu or type in.
Auto-number	Generates an automatically incremented numeric counter for each new issue. Can be used to create an additional custom identifier for issues. Existing issues won't be affected after this field is activated.
Document	Stores a reference to one of the documents in the selected project (current project by default). Users can pick a document from a drop-down list.
VCS Commit	Stores a reference to one of the commits in the selected project (current project by default). Users can pick a commit from a dialog.

Custom field settings

Common settings. The following settings are available for all field types:

Setting	Description
Field name	Name of the custom field as it appears on the issue to all viewers
Description	(Optional) A short description of the field's purpose visible to all viewers. Can be added if the field name is not informative enough.
Type	Determines what type of data can be stored in the field and in what format. For a detailed description of all field types, see Custom field types
Multiple values possible	Enables the field to store more than one value
Required field	Makes input mandatory. An issue cannot be created, unless a value is entered in this field.
Default value	Set a value to pre-populate the field. The value will be stored and displayed in the field until someone inputs a different value. If your field type is Checkbox, the default value is either checked or unchecked.

Type-specific settings. The following settings are only available for certain field types:

Setting	Type	Description
Multi-value	Text, Number, List, Organization member, Issue, Document, VCS Commit	Allow users to enter and store more than one value in the field. This option is set upon the creation of the field and cannot be edited after the field is created.
Open-ended	List	In addition to selecting predefined values, allow users to add new values (list items) to the list right on the spot.
Values	List	Define a list of values (list items) for users to choose from. Enter a value than click Add another to enter another one. Repeat until you have defined all values.
Constraints	Text, Number, Date, Date and Time	Restrict and validate user input by setting constrains for entered values. Depending on the field type, you can specify the minimum and maximum number of characters that can be entered, set a range for date selection, and so on. Pattern. Use Regular Expressions to apply additional restrictions, such as predefined format and order of characters. Error message. Provide a message that will be shown to the users if they enter invalid values.
Source project	Document, VCS Commit	Specify a project from which users will pick documents, commits. The default is set to the current project.

Change custom field order

By default, custom fields are displayed on an issue page in the order they were created, from top to bottom. To rearrange existing custom fields:

On the Issues page, click the Settings button:
On the issues Settings page, go to the Custom Fields tab:
Set the desired order of custom fields by dragging them up or down the list.

Last modified: 18 August 2023