Skills update for handling styling Angular chart tooltips

[radomirchev]

Component / Area

Other

Is your feature request related to a problem?

Yes, whenever I create custom theme using skills and MCP, chart tooltips are not styled accordingly.

Describe the solution you'd like

Skills & documentation feedback — styling Angular chart tooltips

Feedback from a real task on this repo (2026-08-31): "the price-pane tooltip of the
FinJS dock-manager financial chart doesn't match the dark theme; Volume/RSI tooltips do."
Solving it required reverse-engineering igniteui-angular-charts package internals, because
neither the skills here nor the product docs describe how chart tooltips are actually
rendered and themed. This file records what was learned, as concrete change proposals.

The findings below were verified against igniteui-angular-charts 22.0.x by reading the
package source and by driving the running app headless (screenshots in both themes).

---

1. The core knowledge that was missing

Ignite UI Angular charts render tooltips through two completely different mechanisms,
and the styling story is different for each:

Path A — HTML series tooltips (stylable with CSS)

The default per-series tooltips (e.g. the financial chart's volume and indicator panes)
are real DOM elements: an igx-tooltip-container component whose box is the
.ig-tooltip-container-background div. It is authored against CSS custom properties, so
declaring these on the element itself re-themes it:

// Must live in an UNENCAPSULATED stylesheet (ViewEncapsulation.None or global):
// the tooltip is not rendered in your component's template, so emulated
// encapsulation selectors never match it.
.ig-tooltip-container-background {
  --tooltip-container-background-color: var(--ig-gray-100);
  --tooltip-container-text-color: var(--ig-gray-900);
  --tooltip-container-padding: 8px;
  --tooltip-container-font: 11px 'DM Sans', sans-serif;

  // The one thing no custom property carries: the template binds
  // border-color inline to a hardcoded #666.
  border-color: var(--ig-gray-300) !important;
}

Available properties: --tooltip-container-background-color, --tooltip-container-text-color,
--tooltip-container-padding, --tooltip-container-font, --tooltip-container-border-width,
--tooltip-container-border-style. Declare them on the element, not on an ancestor — the
package sets --tooltip-container-background-color: transparent inline on one of its
wrappers, and an inherited value loses to that.

Path B — canvas "pointer" tooltips (NOT stylable with CSS at all)

The financial chart's price pane tooltip (and the Data/Item/Category tooltip
layers generally) is painted on a chart-owned <canvas> — box fill, border, radius,
and (for the data tooltip) the text too. Its positioned wrapper
(.ui-chart-pointer-tooltip-container) is appended to document.body. No stylesheet
can recolour it. This is the single most common trap: an agent (or developer) sees a
white tooltip on a dark theme, reaches for CSS, and it silently does nothing.

Two facts govern it:

1. The box colours come from the mutable module-level export
   DataChartStylingDefaults (public API of igniteui-angular-charts), under the key
   ui-chart-pointer-tooltip, with CSS-property-shaped keys:

   import { DataChartStylingDefaults } from 'igniteui-angular-charts';
   
   (DataChartStylingDefaults as Record<string, unknown>)['ui-chart-pointer-tooltip'] = {
     'background-color': '#141e2e',
     'border-top-color': '#273d58',
     'border-top-width': '1px',
     'border-top-left-radius': '4px',
   };

   Defaults when the key is absent: white box, gray border, 0 radius.

2. The table is read ONCE, when a chart is created (the Angular chart components
   construct their renderer with useDefaultsSource: true, which also means the CSS
   probe classes some non-Angular Ignite UI docs mention — styling a
   .ui-chart-pointer-tooltip CSS class — do not work in Angular). Consequences:

   • The entry must be written before the chart component is instantiated.

   • A runtime theme switch requires recreating the chart; the idiomatic Angular
     pattern is keying it on the palette:

     @for (chartPalette of [palette()]; track chartPalette) {
       <igx-financial-chart ... />
     }

   • The table is global to every chart in the application — restore/delete the entry
     when the feature that owns it is destroyed if other views also render charts.

Text colours of the canvas data tooltip are the only part with public chart inputs —
set toolTipType="Data" and bind:

<igx-financial-chart
  toolTipType="Data"
  [dataToolTipHeaderTextColor]="palette().text"
  [dataToolTipLabelTextColor]="palette().text"
  [dataToolTipValueTextColor]="palette().text"
  [dataToolTipUnitsTextColor]="palette().label"
  [dataToolTipTitleTextColor]="palette().text"
  ...
/>

There are no chart inputs for the tooltip box (dataToolTip* styles text, margins and
badges only) — the defaults-table write above is the only hook.

Dead ends, verified so they aren't re-explored: toolTipType="Data" alone does not fix
the colours (same canvas box); toolTipType="None" kills all tooltips including the
HTML ones; CSS on .ui-chart-pointer-tooltip-container styles only an empty wrapper —
the visible content is canvas pixels.

---

2. Proposed change: igniteui-angular-components/references/charts.md

(Apply to both copies: .claude/skills/... and .agents/skills/... — they are kept in sync.)

1. In Styling & Theming, replace the misleading line

   - **Tooltip**: Controlled via toolTipType and custom tooltip templates

   with

   - **Tooltip**: toolTipType selects the tooltip *behaviour*; styling depends on which of two render paths the tooltip uses — see [Styling chart tooltips](#styling-chart-tooltips)

2. Add a new section “Styling chart tooltips” (and a Contents entry) containing the
   whole of section 1 above, framed as:

   • symptom table (“tooltip is a white box that ignores my theme” → Path B;
     “tooltip is an HTML element” → Path A);
   • the CSS recipe for Path A;
   • the DataChartStylingDefaults + chart-recreation recipe for Path B;
   • the dead-ends list.

3. Add one entry to Common errors and fixes:

   Error 3: chart tooltip ignores CSS / stays white on a dark theme
   The tooltip is canvas-painted, not DOM. Write
   DataChartStylingDefaults['ui-chart-pointer-tooltip'] before the chart is created and
   recreate the chart on theme changes. CSS cannot fix this one.

A working end-to-end implementation exists in this repo:
src/app/samples/grid-finjs-dock-manager/chart-panel/chart-panel.ts
(applyPointerTooltipTheme, the pane-counter cleanup) and chart-panel.html
(the @for-keyed chart) — worth citing from the skill as the reference example.

---

3. Proposed change: igniteui-angular-theming skill

references/common-patterns.md should carry a short “What Sass/tokens cannot reach”
note: chart canvases (series, axes, and the pointer-tooltip box) do not read --ig-*
tokens — they take literal colour strings via chart inputs, and the pointer-tooltip box
only via DataChartStylingDefaults. Point to the charts reference section above. Today an
agent asked to “theme the chart tooltips” lands in this skill and finds nothing telling it
that the theming system is the wrong tool for half the job.

---

4. Suggestions for Ignite UI product documentation

The Angular chart-tooltip topics (Chart Tooltips / Highlighting, Financial Chart) leave
these undocumented; each caused real friction:

1. Document the two rendering paths. Nothing states that Default/Item/Category/
   Data tooltips on some panes are canvas-rendered while per-series tooltips are HTML.
   Every styling question hinges on this distinction.
2. Document DataChartStylingDefaults (and its siblings, e.g.
   SparklineStylingDefaults, ZoomSliderStylingDefaults). It is exported public API and
   the only way to restyle the pointer-tooltip box in Angular, yet it appears in no topic.
   Include the ui-chart-pointer-tooltip key, the accepted sub-keys, and the
   read-once-at-chart-creation caveat.
3. Document the --tooltip-container-* CSS custom properties for HTML tooltips,
   including the inline #666 border-colour that needs !important, and the view
   encapsulation caveat.
4. Call out that CSS-probe styling does not apply to the Angular wrappers. Docs
   content shared across platforms implies .ui-chart-* CSS classes are honoured; the
   Angular components pass useDefaultsSource: true and never query the DOM.

API gaps worth filing as product issues

• The internal DataToolTipLayer already has ToolTipBackground, ToolTipBorderBrush
  and ToolTipBorderThickness dependency properties (the standalone
  IgxDataToolTipLayerComponent for the data chart exposes them as inputs), but the
  category/financial chart facades forward only the text-oriented dataToolTip*
  properties. Forwarding those three as dataToolTipBackground /
  dataToolTipBorderBrush / dataToolTipBorderThickness would make the whole tooltip
  themable with plain, reactive Angular bindings — no defaults table, no chart recreation.
• IgxDataChartComponent has a public styleUpdated() to re-read styling defaults;
  IgxFinancialChartComponent / IgxCategoryChartComponent have none, which is why a
  runtime theme switch currently forces chart recreation.

Proposed API or Usage

Describe alternatives you've considered

No response

How important is this feature to you?

Nice to have

Additional context

No response