Using the Traffic Light KPI field

This guide describes how to work with a Traffic Light KPI custom field that your administrator has already configured. If you don't see the field on your issue screens yet, check with your Jira administrator: most likely it just needs to be added to the right screen.

Capture a value

When the Traffic Light field is part of the Create, Edit, or Transition screen, it appears as a numeric input.

1. Open the create, edit, or transition form.
2. Locate the field (the exact name is set by your administrator, for example "Compliance level").
3. Enter the numeric value.
4. Save your changes.

If the value isn't a valid number, Jira will show "Please enter a valid number." and refuse to save.

You can leave it blank

If the field is not marked required in your project, you can leave it empty. The issue will save and, on the view, a gray indicator will appear to represent the missing value.

Reading the indicator on the issue view

Once saved, the field is shown as a colored indicator next to the numeric value. The color (red, yellow, or green) is determined by your administrator using the thresholds configured on the field's context.

Legend

Below the indicator you'll find a descriptive legend with the ranges defined by your administrator, for example:

🔴 Red: ≤ 30 — 🟡 Yellow: 30 < value ≤ 70 — 🟢 Green: > 70

This tells you, without asking the administrator, what range each color represents and what the desirable situation is.

Tooltip

Hovering over the colored indicator shows a tooltip with the exact range to which the current value belongs (for example, "Red: ≤ 30" or "Green: > 70").

Dark mode

The indicator, legend, tooltip, and numeric value are designed to keep accessible contrast in both light and dark themes of Jira Cloud. Switching themes will not hurt readability.

Why is the indicator gray sometimes?

The indicator renders gray when:

• The field is empty on the issue, or
• The administrator has not yet configured thresholds for the field's context (project / issue type).

Check with your administrator if you were expecting to see a color.

"Lower is better": what it means

Some KPIs measure situations where a lower value is desirable (for example, resolution time or open incidents). For those, your administrator may have enabled Lower value is better on the field's context.

When this mode is active:

• 🟢 Green means low values (better performance).
• 🔴 Red means high values (worse performance).
• 🟡 Yellow stays in the intermediate range.

The legend and the tooltip reflect this inversion automatically, so you can always read the indicator without ambiguity.

Searching issues by Traffic Light value

You can use JQL to locate issues by the field's numeric value:

"Compliance level" < 30

"Compliance level" >= 70 AND project = "ACME"

"Compliance level" is not EMPTY

Replace Compliance level with the exact name your administrator gave the field.

JQL works on the value, not the color

To list, for example, "all red issues", combine JQL operators with the context's thresholds: "Compliance level" <= 30 (in the default mode). Jira's engine doesn't know about the color — it always operates on the stored number.