ZoomCharts Documentation
Version: 1.21.20 (2026-09-08)
Switch to Version 2.0 (BETA)

FacetChart.settings.comments

This section is defined by the type LinearChartSettingsComments.

Properties

alwaysShowMarkerTooltip: boolean
Default value: false

When enabled, a tooltip is shown for every visible comment marker, anchored beside the marker per {@link markerTooltipPosition}. When disabled, a tooltip appears only while hovering a marker and follows the mouse cursor (still respecting {@link markerTooltipPosition}).

chartPreviewEnabled: boolean
Default value: true

When true (default), comment markers and shapes are drawn in the chart area. When false, they are hidden in the chart but still listed in the side panel when it is open.

defaultTextColor: string
Default value: null

Fallback fill color for new comments / the editor when a comment has no {@link SettingsComment.labelStyle} text fillColor. Dark themes override this to a light color so draft text stays readable.

enabled: boolean
Default value: false
height: number
Default value: 0
iconMarkerPosition: "default" | "top" | "bottom"
Default value: "bottom"
markerOverlap: "default" | "none"
Default value: "default"

How chart comment markers resolve overlaps with each other.

  • default: bottom markers use moveup, top markers use movedown, and markers with {@link SettingsComment.iconMarkerOffset} keep an exact position (none).
  • none: markers always draw at their layout position (may overlap).
markerTooltipPosition: "top" | "right" | "left" | "bottom"
Default value: "top"

Preferred side for comment marker tooltips. Falls back to the opposite side when the preferred side does not fit in the chart area.

  • top (default): above the marker, else below
  • bottom: below the marker, else above
  • left: left of the marker, else right
  • right: right of the marker, else left
panelContents: "visible" | "allLoaded" | "allAtLevel"
Default value: "visible"

Controls which comments appear in the side panel.

  • visible (default): comments whose marker center, shape endpoint, or (when there is no marker) data-item bounds intersect the chart.
  • allLoaded: every comment from data currently loaded at this level.
  • allAtLevel: every comment for the current aggregation/drilldown level, supplied by {@link panelItemsFunction} (not limited to currently loaded chart data). Falls back to allLoaded when the function is missing or returns null/undefined.
panelCountFunction: (info: LinearChartCommentsPanelCountInfo) => number
Default value: null

Optional app-provided value for the panel titlebar / toolbar comment counter. Intended for a global (or as-global-as-possible) total: especially with {@link panelContents} === "allAtLevel", return the size of the full multi-level catalog. When unset or when the function returns null/undefined, counters fall back to the current panel list length (the closest honest figure for the active mode).

Parameters
Return value
Data type: number
panelItemsFunction: (info: LinearChartCommentsPanelItemsInfo) => Array<LinearChartCommentPanelItem>
Default value: null

App-provided source of side-panel comments for {@link panelContents} === "allAtLevel". Should return every comment that belongs to the current aggregation/drilldown level. Chart markers are unaffected and still come only from loaded data.

Parameters
Return value
panelLevels: LinearChartSettingsCommentsPanelLevels
View section details

Optional "Comments by Level" band below the titlebar (when both are enabled). Lists dataset levels plus an All pseudo-level for navigating and aggregating comments across levels.

panelOpen: boolean
Default value: true

When true (default), the comments side panel starts open and claims its configured width from the chart area. When false, it starts closed (zero width). Toggled at runtime via the comments toolbar dropdown or {@link ChartComments.setPanelOpen}.

panelOpenAnimationDuration: number
Default value: 0.2

Duration in seconds for animating the panel open/close width change ({@link FixedDurationLinearAnimation}). The chart area reflows with the animated width. Use 0 for an instant snap.

panelTitlebar: LinearChartSettingsCommentsPanelTitlebar
View section details

Optional fixed titlebar above the scrollable comment list (icon, title, optional total count, separator). Disabled by default.

placementPreviewComment: (args: LinearChartCommentPlacementPreviewArguments) => LinearChartSettingsComment
Default value: null

Optional app callback that builds a {@link SettingsComment} used only for the live placement preview (ghost marker while adding a data-point or canvas comment). Must not persist comments or advance id counters.

When unset, data-point mode keeps the range band on drag and no mode draws an icon preview.

Parameters
Return value
placementPreviewOpacity: number
Default value: 0.5

Opacity multiplier applied when painting {@link placementPreviewComment} (relative to the current canvas alpha). Default 0.5.

scrollAnimationDuration: number
Default value: 0.2
toolbarDropdown: LinearChartSettingsCommentsToolbarDropdown
View section details

Per-item icon colors for the comments toolbar dropdown menu. Icons render with {@code currentColor}; these values are applied to the icon wrapper at build time.

toolbarShowCount: boolean
Default value: true

When true (default), the comments toolbar dropdown shows the same resolved comment total as the panel titlebar counter ({@link panelCountFunction} or panel list length) instead of the localized {@link SettingsLocalizationToolbar.commentsEditButton} label. The button title/tooltip remains the add-comment string.

width: number
Default value: 0
X