Customize Card Colors

Overview

Card colors in Planningboard are set via the Item Script in the widget’s Advanced Properties. The cli.cardColor property accepts any CSS HEX or named color value and can be set conditionally based on any work item field — including workflow status, custom fields, or parent-item relationships.

Planningboard does not support automatic card coloring based on custom enumeration fields (such as topic category or component). This differs from Nextedy SCRUMBOARD, which supports enum-based card coloring out of the box. In Planningboard, all conditional coloring must be implemented via an Item Script.

How to set a card color

Navigate to the Polarion LiveDoc or Wiki page that contains your Planningboard widget.
Enter edit mode and open the widget’s Advanced Properties section.
Locate the Item Script field.

Step 2: Set `cli.cardColor` in the script

Add a JavaScript expression that sets cli.cardColor to a color value. The color is applied as the card’s background. Simplest form — fixed color for all cards:

cli.cardColor = "#e3edff";

Conditional color based on a work item field:

var crType = wi.getValue("crType");
if (crType != null && crType.getId() === "parentCR") {
  cli.cardColor = "#e3edff";
}

In this example, wi is the current work item (Polarion IWorkItem) and wi.getValue("crType") reads the crType custom field. Replace "crType" and "parentCR" with your actual field ID and enum ID.

Step 3: Save and reload

Save the widget configuration and reload the page. Cards matching the condition will display with the new background color.

Right-click a card and choose Inspect to preview the applied background color in real time. This helps you confirm the script is working and lets you fine-tune HEX values visually before committing.

Color cards by parent item

A common pattern is to let child items inherit a color from their parent — for example, all items belonging to the same System Requirement share a color. This makes it easy to trace hierarchy on a dense board.

Planningboard showing cards colored by parent item — one swimlane has blue cards and another has red cards, with the Unplanned sidebar open on the right

System Requirement parent item with custom field pbColor set to blue, and three child work items each inheriting card color #00c3ff

Step 1: Create a custom string field on the parent type

In Polarion Administration, add a custom field to your parent work item type:

Field ID: pbColor (or any name you choose)
Type: String

Polarion Custom Fields Designer showing the systemrequirement custom fields file with the pbColor field (type: String) highlighted by an arrow

Step 2: Populate the field on parent items

On each parent work item, enter a color name into the pbColor field: blue, red, green, or yellow.

Polarion work item PB-338 (System Requirement) showing the Custom Fields section with PB Color field set to 'yellow', highlighted by an arrow

Step 3: Add the Item Script

Paste the following into the Item Script field in the widget’s Advanced Properties:

// Allow card attributes to be modified by this script
cli.readonly = false;

// Walk direct links to find the parent System Requirement
var i = wi.getLinkedWorkItemsStructsDirect().iterator();
var systemrequirement = null;

while (i.hasNext()) {
  var link = i.next();
  if (link.getLinkRole() && link.getLinkRole().getId() === "implements") {
    systemrequirement = link.getLinkedItem();
  }
}

// Apply the parent's color to this card
if (systemrequirement != null) {
  var pbColor = systemrequirement.getValue("pbColor");
  if (pbColor && pbColor.trim() !== "") {
    pbColor = pbColor.toLowerCase().trim();
    if (pbColor === "blue")   cli.cardColor = "#00c3ff";
    else if (pbColor === "red")    cli.cardColor = "#ff4d4d";
    else if (pbColor === "green")  cli.cardColor = "#00f57f";
    else if (pbColor === "yellow") cli.cardColor = "#ffd700";
  }
}

The script uses the "implements" link role to identify the parent. If your project uses a different link role (e.g. "is_part_of" or a custom role), replace "implements" with that role’s ID — use the exact ID as configured in Polarion, not the display label.

You are not limited to named colors. Replace or extend the if/else block with any HEX values:

if (pbColor === "teal") cli.cardColor = "#009688";

Item Script API reference

The table below lists the cli properties relevant to card color customization. These are the confirmed properties available inside an Item Script.

Property	Type	Description
`cli.cardColor`	String	Background color of the card. Accepts CSS HEX (`#e3edff`) or named colors (`blue`).
`cli.color`	String	Frame (border) color of the card.
`cli.readonly`	Boolean	Set to `false` to allow the script to write card attributes.
`cli.fieldsLine`	String	HTML text displayed below the card title.
`cli.label`	String	Short text label shown on the card.
`cli.tooltip`	String	Text shown when hovering over the card (supports HTML).

The main objects available in every Item Script:

Object	Description
`wi`	The current work item via the classic Polarion API (`IWorkItem`). Use `wi.getValue("fieldId")` to read custom fields.
`workitem`	The same item via the rendering API. Use `workitem.fields()` to access field renderers.
`cli`	The client-side card configuration object. Properties set here control what the card displays and how it looks.

Decision guide: which approach to use

Decision tree for choosing a card-color approach: fixed value, own-field-based, parent-inherited, or unsupported custom enumeration field

Verification

After saving the Item Script and reloading the page, you should now see:

Cards that match your condition displaying the assigned background color.
Cards that do not match the condition retaining the default (uncolored) appearance.
If you implemented parent-color inheritance, all child items linked to the same parent appear with the same color.

If cards show no color change, verify that:

The cli.readonly = false; line is present if needed.
The field ID and enum ID strings match exactly what is configured in Polarion (IDs are case-sensitive).
The pbColor field (or equivalent) is populated on the parent items.
The correct link role ID is used in getLinkRole().getId().

Overview

How to set a card color

Step 1: Open widget parameters

Step 2: Set `cli.cardColor` in the script

Step 3: Save and reload

Color cards by parent item

Step 1: Create a custom string field on the parent type

Step 2: Populate the field on parent items

Step 3: Add the Item Script

Item Script API reference

Decision guide: which approach to use

Verification

See also

​Overview

​How to set a card color

​Step 1: Open widget parameters

​Step 2: Set cli.cardColor in the script

​Step 3: Save and reload

​Color cards by parent item

​Step 1: Create a custom string field on the parent type

​Step 2: Populate the field on parent items

​Step 3: Add the Item Script

​Item Script API reference

​Decision guide: which approach to use

​Verification

​See also

Overview

How to set a card color

Step 1: Open widget parameters

Step 2: Set `cli.cardColor` in the script

Step 3: Save and reload

Color cards by parent item

Step 1: Create a custom string field on the parent type

Step 2: Populate the field on parent items

Step 3: Add the Item Script

Item Script API reference

Decision guide: which approach to use

Verification

See also