Adding custom fields

Still need help?

The Atlassian Community is here for you.

Ask the community

You can create a custom field to collect information that isn’t available in the default system fields. Before you start, make sure to read our tips for creating custom fields so you don’t end up cluttering your Jira instance with too many fields.

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

For all of the following procedures, you must be logged in as a user with the Jira Administrators  global permission.

Tips for creating custom fields

After creating thousands of custom fields, here’s some best practices we’d like to share:

  • Limit the number of custom fields — Be careful how many custom fields you define in Jira. More than a thousand is a large number and may affect Jira's performance.

  • Combine field content — If just want to make sure that someone remembers to enter some information, then consider a multi-line custom text field with a text template as a default value. You may also want to try using a "table grid" custom field which lets you enter data in a searchable table.

  • Don't duplicate names — Don't create new custom fields with the same name as other existing custom fields. Always check to see whether a custom field with the same name already exists before you create it. If you do, then choosing the correct field in JQL searches can become confusing for users. Also, don't create custom fields with the same name as the standard Jira fields. For example, having two "Status" fields is particularly confusing. 

  • Make names as generic as possible — Give custom fields non-specific names that can be reused in other places later on. For example, instead of naming a field "Marketing Objective", name the field "Objective", and provide a description in the field configuration that states the Jira projects where that field is used.

Add a field directly to an issue

To add a field to an issue:

  1. Open an issue.

  2. Select Admin > Add field

Add a field from the custom fields view

To add a field on the Custom fields page:

  1. Go to Administration > Issues, and select Custom fields.

  2. Select Add custom field

  3. In Select a Field Type, select All to make sure you can see all available field types. 

  4. Select a field type and click Next.

  5. Configure the selection criteria for your field, as shown in the example for the Checkboxes field below: 

    The Field Name will appear as the custom field's title in both entering and retrieving information on issues, whereas the Field Description is displayed beneath the data entry field when entering new issues and editing existing issues, but not when browsing issues.

  6. Select Next.

  7. Configure the context for your field and click Next.

    What are contexts?

    Custom field contexts are different configurations of the same field. By configuring multiple contexts, you can use different default values and options for certain projects, or make the field be applicable only to chosen issue types or projects. It’s generally a good idea performance-wise to limit a custom field to only the projects that will actually use it. You can configure context later

  8. Click Create.

Associating your field with a screen

After you create a custom field, you’ll be moved to the Screens page. Here you can choose what screens your custom fields should be displayed on, for example Create Issue screen or Edit screen.

  1. Have a look at the list of available screens and their projects.

  2. Select a checkbox next to the desired screen, and click Update.

Next steps

If you wish to change the context, see Configuring a custom field. You can also find more custom fields from apps listed on the Atlassian Marketplace (e.g. the Jira Toolkit). To build your own custom field types, see the tutorial at the Jira Developer Documentation.

tip/resting Created with Sketch.

Do more with Jira

To help you add custom fields to Jira, use one of the apps available on the Atlassian Marketplace:  

Last modified on Apr 14, 2022

Was this helpful?

Provide feedback about this article
Powered by Confluence and Scroll Viewport.