Perspective XY Chart Line Color: Resolving Property Mismatch

Overview

The Perspective XY Chart component in Inductive Automation's Ignition platform provides a flexible way to display either time-series or XY data on a configured view. When a series is added without an explicit line color, the property editor displays a default gray swatch while the rendered chart uses a color chosen by the underlying charting library. This visual mismatch between the property UI and the rendered line causes confusion during commissioning and is the most common misinterpretation of the series.#.line.appearance.stroke.color property.

This reference documents the exact behavior, the underlying mechanism, the recommended configuration workflow, and the verification checks required to make the property editor reflect the actual rendered line color. All paths and property names are taken from the official Ignition 8.1 Perspective user manual. See the Perspective XY Chart documentation and the Inductive University XY Chart training video for the canonical reference set.

Problem Details

When an engineer adds an XY Chart to a Perspective view, configures a series via props.series, and inspects the line appearance sub-property, the following behavior is observed:

• The series.<index>.line.appearance.stroke.color property displays a default gray swatch (or an empty value) in the property editor.
• The rendered line on the chart uses a different color (blue, green, red, etc.) chosen automatically by the charting library.
• Editing the color value in the property editor updates the rendered line correctly, but reverting to the default gray does not restore the auto-picked color — the line is rendered with no visible color or the next palette entry.

The mismatch is not a bug in the property binding pipeline; it is a deliberate delegation of color selection to the charting engine when the user has not specified a value. The property name (stroke.color) is intuitively correct, but the default state does not reflect what is actually being drawn on the canvas.

Root Cause

The Perspective XY Chart delegates initial color selection to the third-party charting library it embeds. The library is responsible for:

1. Ensuring that no two series in the same chart use the same color.
2. Ensuring adequate contrast between adjacent series for legibility.
3. Avoiding colors that conflict with the active theme background or axis chrome.

To satisfy these constraints without writing back to the property tree on every render, the library reads the property as a hint, applies its own palette when the hint is empty or equal to the default placeholder, and uses the hint directly when the user provides a non-default value. The placeholder gray in the property editor is therefore not a color value; it is a visual indicator that the property is unset.

Prerequisites

Before configuring line colors, confirm the following:

• Ignition 8.1.x gateway with the Perspective module licensed and active.
• A Perspective project loaded in the Designer with a view open for editing.
• An XY Chart component dropped onto the view from the Component Palette (Chart category → XY).
• At least one data source configured and bound to props.dataSources. Time-series sources should return tag history data; XY sources should return paired numeric arrays.
• Read access to the Perspective XY Chart user manual page for the canonical property tree.

Step-by-Step Resolution

Follow the steps below to make the rendered line color match the property editor value and to lock the color so it does not change when additional series are added.

Step 1 — Add the XY Chart Component

1. In the Designer, open the target view.
2. From the Component Palette, select the Chart category.
3. Drag the XY component onto the view canvas.
4. Resize and position the chart as required for the layout.

Step 2 — Configure the Data Source

1. Select the chart component on the canvas.
2. In the Property Editor, expand props → dataSources.
3. Add a new data source object. The minimum structure is:
   { "key": "series1", "type": "taghistorian", "tagPath": "[default]Path/To/Tag" }
4. For XY data, set type to "xy" and provide paired x and y arrays or a query binding that returns them.

Step 3 — Add a Series Entry

1. Expand props.series in the Property Editor.
2. Add a new series object. The minimum structure is:
   { "name": "Series 1", "dataSource": "series1", "line": { "appearance": { "stroke": { "color": "", "width": 1 } } } }
3. Note that the color field is intentionally left as an empty string. This is the value that triggers the auto-pick behavior.

Step 4 — Set an Explicit Color

1. In the Property Editor, locate series.0.line.appearance.stroke.color.
2. Click the color swatch and choose an explicit value (hex, RGB, or named CSS color). For example: "#1f77b4".
3. Confirm in the Designer preview that the rendered line now matches the selected color.

Step 5 — Bind the Color (Optional)

To make the color dynamic, bind series.0.line.appearance.stroke.color to a tag, a parameter, or an expression. Recommended expression patterns:

if({[default]Line/OverrideColor} <> "",
   {[default]Line/OverrideColor},
   "#1f77b4")

This binding returns the operator override when present, otherwise falls back to the explicit color. Avoid binding to an empty string unless you intend to re-enable the auto-pick behavior.

Step 6 — Repeat for Additional Series

When adding series 1, 2, 3, etc., assign each a distinct explicit color to prevent the library from re-picking and to make the property editor and the canvas agree. A safe starting palette is shown in the table below.

Recommended Starting Palette

Property Reference

The full property tree for the line appearance is:

series.<index>.line.appearance.stroke.color   (string, CSS color)
series.<index>.line.appearance.stroke.width   (number, pixels)
series.<index>.line.appearance.stroke.dash    (array, pixel pattern)
series.<index>.line.appearance.shape          (object, marker config)
series.<index>.line.appearance.fill           (object, area fill config)

Only the color field is delegated to the library when empty. width, dash, shape, and fill always reflect their explicit values because the library does not auto-pick them.

Data Source Configuration

The XY Chart supports three data source shapes:

1. Time-series (tag historian): The library maps the timestamp domain to the X axis and the value to the Y axis. type must be "taghistorian".
2. XY pairs (database or expression): The library maps explicit X and Y arrays to the axes. type must be "xy" and the payload must contain x and y numeric arrays of equal length.
3. Custom (function-bound JSON): The component accepts any payload that the library can interpret. type is set to "custom" and a binding supplies the data.

The data source type does not affect color behavior. The library applies the same auto-pick logic to all three shapes.

Charting Library Behavior

The embedded charting library maintains an internal palette index that increments each time a new series is added without an explicit color. The index wraps at the palette length (typically eight colors) and resets when the chart is re-rendered from a new data set. The auto-picked color is not deterministic across re-renders unless the series order is stable. To guarantee a specific color for a specific series, always set color to an explicit value.

Theme Considerations

The auto-picked palette is tuned for the default light theme. On the dark theme, the lower-order palette entries (especially gray) may have insufficient contrast against the canvas. Set explicit colors when the project is deployed against a dark theme to avoid legibility regressions.

To apply a project-wide palette, bind each series.<i>.line.appearance.stroke.color to a property of a custom property sheet (for example, params.chartColors) and let the view pass a single array down to all charts. This keeps the palette in one location and prevents drift between views.

Verification

After configuring explicit colors, validate the result with the following checks:

1. Open the view in the Designer and confirm the rendered line color matches the swatch in the Property Editor.
2. Open a web browser session pointed at the same project and confirm the same color renders. The library applies the same palette to both Designer and client.
3. Add a second series with an empty color and confirm the first series retains its explicit color while the second receives an auto-picked color from the remaining palette entries.
4. Bind a tag to color and change the tag value at runtime. The line should update within one render cycle (typically under 200 ms on a local client).

Troubleshooting Matrix

Best Practices

• Always set explicit colors for production screens. Reserve auto-pick for prototypes and ad-hoc debugging.
• Centralize the palette in a project parameter or a UDT instance to keep colors consistent across views.
• Document the palette assignment in a property sheet comment so that future engineers know which color belongs to which series.
• Avoid binding color to an expression that can return an empty string unless the auto-pick behavior is desired.
• For accessibility, ensure the chosen palette passes WCAG 2.1 AA contrast (3:1 for non-text graphical objects) against both light and dark themes.

FAQ