> ## Documentation Index
> Fetch the complete documentation index at: https://learn.nextedy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Customize Tooltips

> Configure what appears when users hover over cards and capacity bars on the Nextedy PLANNINGBOARD.

Planningboard surfaces two distinct tooltip types:

* **Card tooltips** — shown when hovering over a work item card on the board
* **Capacity tooltips** — shown when hovering over the capacity bar of a Plan column

Both are configurable through scripting. Card tooltips use the `cli.tooltip` property in an Item Script; capacity column tooltips use the `columnTooltipTemplate` configuration option.

***

## Before you begin

* You need edit access to the Planningboard widget parameters on the LiveDoc or Wiki page.
* Familiarity with the `wi` and `cli` scripting objects helps — see [Customize Card Content](/planningboard/guides/customization/card-content) for an introduction to Item Script.
* Capacity tooltips require capacity loading to be enabled (`capacityLoad = true`). See [Configure Capacity Tracking](/planningboard/guides/configuration/capacity-configuration).

***

## Customize card tooltips

Card tooltips appear when a user hovers over any work item card on the board. By default, no custom tooltip is set. You define the tooltip content using the `cli.tooltip` property inside the **Item Script**.

### Step 1: Open the widget parameters

Open the page containing the Planningboard widget in edit mode and open the **Advanced Properties** section of the widget.

### Step 2: Add an Item Script

In the **Item Script** field, set `cli.tooltip` to any string. The value supports HTML for richer formatting.

**Example — show the work item ID and description on hover:**

```javascript theme={null}
cli.tooltip = "<strong>" + wi.getId() + "</strong><br>" + wi.getDescription();
```

**Example — show a custom field value in the tooltip:**

```javascript theme={null}
var riskLevel = wi.getValue("riskLevel");
if (riskLevel != null) {
  cli.tooltip = "Risk: " + riskLevel.getName();
} else {
  cli.tooltip = wi.getTitle();
}
```

**Example — show assignee and status together:**

```javascript theme={null}
cli.tooltip =
  workitem.fields().assignee().render().htmlFor().forFrame() +
  " &mdash; " +
  workitem.fields().status().render().withText(true).htmlFor().forFrame();
```

### Step 3: Save and verify

Save the widget. Hover over any card on the board. The tooltip should appear with the content you defined.

<Tip>
  `cli.tooltip` accepts HTML strings. You can use `<br>`, `<strong>`, `<em>`, and inline styles to format multi-line or highlighted tooltips. Keep the content concise — long tooltip text is hard to read at small sizes.
</Tip>

<Warning>
  If `cli.tooltip` is set to `null` or an empty string, no tooltip appears. Ensure the field or value you are reading from `wi` is populated in Polarion before testing — custom field data must exist on the work item for it to appear in the tooltip.
</Warning>

***

## Customize capacity tooltips

Capacity tooltips appear when hovering over the **capacity bar** of a Plan column in the calendar header. They are only active when capacity loading is enabled on the board.

### Default capacity tooltip

When no custom template is configured, the default tooltip shows aggregate values:

```text theme={null}
Capacity / Done / Todo / Available
```

This is the fallback shown automatically when `columnTooltipTemplate` is not set.

### Configure a custom capacity tooltip

The `columnTooltipTemplate` option accepts either a string template or a JavaScript function that receives `column` and `row` objects. You set this through the **Config Script** in the widget's Advanced Properties.

**Example — per-user allocation breakdown:**

```javascript theme={null}
scheduler.columnTooltipTemplate = function(column, row) {
  var html = "<strong>" + column.text + "</strong><br>";
  if (column.users) {
    column.users.forEach(function(user) {
      var avail = user.available;
      var color = avail < 0 ? "color:red;" : "";
      html +=
        "<span style='" + color + "'>" +
        user.name + ": " +
        avail + " / " + user.allocated + " / " + user.total +
        "</span><br>";
    });
  }
  return html;
};
scheduler.setCurrentView();
```

The `setCurrentView()` call is required after programmatically changing the tooltip template — it triggers a re-render so the new template takes effect immediately.

<Tip>
  Overallocated users are best indicated with red text (`color: red`) on negative available values. This is the pattern used in standard Nextedy capacity reports and is immediately recognizable to planning teams.
</Tip>

<Warning>
  `setCurrentView()` must be called after any programmatic change to `columnTooltipTemplate`. Without it, the old tooltip format remains until the next natural board refresh.
</Warning>

***

## Tooltip data flow

The diagram below shows how the two tooltip types relate to their data sources and configuration points:

<Frame>
  <img src="https://mintcdn.com/none-17b4493f/zUlmOSLBIQ0HyaAX/planningboard/diagrams/guides/customization/tooltips/diagram-1.svg?fit=max&auto=format&n=zUlmOSLBIQ0HyaAX&q=85&s=a5a7f913f63e708173972a181a848c49" alt="Data flow diagram showing hovering a card triggers the Item Script's cli.tooltip through the wi/workitem API to show a card tooltip, while hovering the capacity bar triggers the Config Script's columnTooltipTemplate through column/row objects to show a capacity tooltip" width="640" height="350" data-path="planningboard/diagrams/guides/customization/tooltips/diagram-1.svg" />
</Frame>

***

## Available scripting objects

| Object                  | Description                                                                                                                                                    |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `wi`                    | The current work item (classic Polarion IWorkItem API). Access field values with `wi.getValue("fieldId")`, IDs with `wi.getId()`, titles with `wi.getTitle()`. |
| `workitem`              | The same item through the rendering API. Use `workitem.fields().fieldName().render().htmlFor().forFrame()` to render fields as HTML.                           |
| `cli`                   | Client-side card configuration. Set `cli.tooltip` to a string (HTML supported).                                                                                |
| `cli.tooltip`           | String. Defines the text shown when hovering over the card. Supports HTML.                                                                                     |
| `columnTooltipTemplate` | Config Script property. A string template or function returning HTML for the capacity bar tooltip.                                                             |

***

## Common pitfalls

<Warning title="Capacity tooltip not appearing">
  Capacity tooltips only appear when `capacityLoad` is enabled in the widget parameters. If the capacity bar is not visible on the board, the tooltip will not appear either. See [Configure Capacity Tracking](/planningboard/guides/configuration/capacity-configuration) to enable it.
</Warning>

<Warning title="Tooltip shows raw object text">
  If `cli.tooltip` is set to a Polarion enum option without calling `.getName()`, the tooltip displays the raw `EnumOption[...]` object string instead of the label. Always call `.getName()` on enum-typed fields:

  ```javascript theme={null}
  var status = wi.getValue("status");
  cli.tooltip = status != null ? status.getName() : "";
  ```
</Warning>

<Warning title="Custom field returns null">
  If a custom field has no value on the work item, `wi.getValue("fieldId")` returns `null`. Always guard with a null check before using the value in a tooltip string to avoid rendering `null` as text.
</Warning>

***

## You should now see

* Hovering over any work item card shows the tooltip content defined in your Item Script.
* Hovering over a Plan column's capacity bar shows either the default aggregate values or your custom per-user breakdown.
* Overallocated users (negative available hours) appear in red in a custom capacity tooltip.

***

## See also

* [Customize Card Content](/planningboard/guides/customization/card-content) — configure `cli.fieldsLine`, `cli.cardColor`, and other card properties alongside tooltips
* [Customize Card Appearance](/planningboard/guides/customization/card-appearance) — adjust card height, colors, and layout
* [Configure Capacity Tracking](/planningboard/guides/configuration/capacity-configuration) — enable the capacity bar that drives capacity tooltips
* [Visualize Capacity Load](/planningboard/guides/capacity/capacity-visualization) — understand what the capacity bar displays
* [Item Scripts](/planningboard/guides/advanced/item-scripts) — full reference for the Item Script execution environment
* [Config Scripts](/planningboard/guides/advanced/config-scripts) — full reference for the Config Script execution environment

<Accordion title="Sources">
  **KB Articles**

  * Planningboard: Customizable Statistics and Capacity Indicators
  * Customize the content of the card
  * Planningboard interface & basic interactions

  **Support Tickets**

  * [#6174](https://support.nextedy.com/helpdesk/tickets/6174)
  * [#6523](https://support.nextedy.com/helpdesk/tickets/6523)
  * [#6612](https://support.nextedy.com/helpdesk/tickets/6612)

  **Source Code**

  * `capacityTooltipRendering.cy.ts`
  * `customProgressTooltip.cy.ts`
  * `viewLicense.vm`
  * `PlanningBoardWidget.java`
  * `PlanningBoardWidgetRenderer.java`
</Accordion>