Options & series

Annotations

• annotations?: ReadonlyArray<AnnotationConfig>: overlays (lineX, lineY, point, text). position.space: 'plot' uses fractions [0,1] for x/y. Full guide: Annotations API. Authoring: annotation-authoring/.

Series Configuration

• SeriesType'line' | 'area' | 'bar' | 'scatter' | 'pie' | 'candlestick' | 'ohlc' | 'heatmap' | 'band' | 'errorBar' | 'impulse' | 'pointCloud3d' | 'surface3d'
  See types.ts.
• StepMode'before' | 'middle' | 'after'
  digital / step connection for line and area (not a series type). Boolean step: true ≡ 'after'.
• coordinateSystem
  'cartesian2d' (default) | 'cartesian3d'. 3D charts use a separate depth + camera path; only pointCloud3d / surface3d are valid there. Full 3D API: 3D charts.
• Sampling (cartesian)
  sampling?: 'none' | 'lttb' | 'average' | 'max' | 'min', samplingThreshold?: number (default 5000). Zoom-aware resampling when data zoom enabled. On the GPU decimation path (lttb/min/max, gap-free lines), effective bucket count is also capped by plot width (targetBuckets = min(samplingThreshold, max(128, 2×plotWidthDevicePx), N)) — intentional screen-space LOD on narrow multi-chart slots; see performance — GPU targetBuckets.
• visible?boolean
  hide series from rendering and interaction. Legend toggle updates both.
• Data identity / in-place mutation
  ChartGPU treats series data by reference identity for hot paths (setOption resolve, content hashing, GPU upload skip, area geometry cache). Mutating point values under a stable array / columns object without replacing the reference may not be detected. Prefer a new array (or appendData(...)) when content changes. Axes-only / presentation-only updates that re-pass the same data reference are intentionally O(1) on the data path.
• Series array identity reuse (axes-only setOption)
  When consecutive setOption calls re-pass the same series config object identities (outer series array may be the same or a new array wrapping the same elements) and theme/palette refs are unchanged, ChartGPU may reuse the entire previous resolved series array without re-walking each series. Treat the outer series array and each series config object as immutable for this path: to change data, color, visibility, style, or candlestick priceLabel, pass a new series element object (or a new series array of new objects). Index assignment (series[i] = {...}) is detected; mutating properties under a stable element object (e.g. series[i].data = newData, series[i].priceLabel = false) is not detected on the full-array path.
• Full rewrite (setOption with a new data array every frame)
  When the data reference changes, ChartGPU uses an O(1) content stamp (not a full float hash) for dirty tracking. GPU buffers are reused when capacity fits; pack goes into retained staging. Tooltip off skips ChartGPU hit-test columnar rebuild until hitTest() or tooltip re-enable (dual-store relief). The coordinator may keep your data array by reference until appendData — append always copies into owned columns and never mutates caller { x, y } arrays.
• Y-only DataStore rewrite (lines)
  When length is stable and every x matches the previous pack, only y floats are rewritten in CPU staging; GPU uploads a dense N×4 y channel and a compute pass rewrites y lanes into interleaved storage (not a full N×8 writeBuffer). Length change, any x change, any non-finite x in the series or staging (including stable null gaps), or modular ring layout force a full interleaved rewrite. Unsorted Brownian xy (group 3) never hits this path.
• Equal-N y-only scatter (const radius)
  When x is stable (e.g. x = i), scatter uses dual x/y instance buffers and uploads only the y channel (N×4). Index-sorted equal-N rewrites with sampling: 'lttb' (matching prior sampling + threshold) under performance.lod: 'auto' re-bind y at the frozen prior LTTB index set in O(k) instead of full O(N) LTTB — approximate hold: newly emerging y extrema between retained indices do not appear until full LTTB resumes (length, x change, sampling/threshold change, or performance.lod: 'strict'). Under strict, plain 'lttb' always full-recomputes on y change. min/max/average always re-sample. Brownian xy updates stay on the full path.
• Dense scatter draw (const radius)
  When points-per-plot-pixel is high and performance.lod !== 'strict', drawn marker radius may compact toward ~1 device pixel (draw-only; does not change sampling or uploaded point count). Low-density charts and strict keep full symbolSize.
• Dense line draw (hairline)
  When a line series has ≥ ~25 000 draw / displayed points (raw stroke length, or GPU-decimation bucket / pointCountOverride instance count) and performance.lod !== 'strict', ChartGPU switches draw only to a native 1 device-px line-list hairline (denseHairline). Those segments are drawn in a post-resolve sampleCount:1 pass (not under main 4× MSAA overdraw). Series lineStyle.width config is unchanged. Mid-N GPU-decimated series (e.g. 50k–500k raw LTTB’d to a few thousand buckets) keep full AA quads + configured width when draw N is low. Multi‑M residency gate: when GPU decimation keeps raw residency ≥ ~1 000 000 points, hairline policy may use that raw count even though draw instance count is the smaller bucket N — multi‑M FIFO / streaming exits 4× MSAA AA-quad fill while still drawing the LTTB sample. Applies to all high-N lines under auto LOD, not only unsorted full rewrites.
• Multi-series dense hairline (total-segment budget)
  When the chart has ≥ 2 visible line series and the approximate total segment count visibleLineSeriesCount × max(0, pointCount − 1) is ≥ ~500 000 (equal-N approximation using each series' own point count) and lod is auto, those lines also enter denseHairline even if each series is below the 25k per-series threshold. Example: 1000 series × 1000 points hairlines; 500 × 500 stays standard AA. Visual tradeoff: multi-series stress charts draw 1 device-px strokes instead of thick width-2 AA quads. Does not change sampling or uploaded data.
• Dense multi-M draw stride (mountain fill + multi-M hairline stroke)
  When N ≥ ~1 000 000 and drawn segments would exceed max(8192, 4× plotWidthDevicePx) and lod is auto, ChartGPU caps drawn consecutive-segment instances via an index stride (shared denseDrawLod policy for area fill and dense hairline stroke). GPU residency and sampling stay unchanged — under sampling: 'none' the full raw series remains resident. Series below 1M (including 250k–500k demos) keep full N−1 geometry under auto. At multi-M this may draw ≪ N−1 segments; use performance.lod: 'strict' for full geometry. Dense mountain fill may also defer to sampleCount:1 (post-resolve / dense-only direct path when no annotations or pointer overlays).
• performance.lod
  'auto' (default) enables dense hairline / scatter radius compaction / mountain fill+stroke draw-stride and approximate equal-N LTTB index freeze; 'strict' always honors configured line width and marker size, full N−1 mountain geometry, and full-recomputes LTTB on equal-N y updates. See Performance guide.
• Main scene MSAA (library-wide)
  Main series pass and overlay UI both use 4× MSAA (MAIN_SCENE_MSAA_SAMPLE_COUNT / ANNOTATION_OVERLAY_MSAA_SAMPLE_COUNT) by default, or 1× when antialias: false is passed at create. Dense hairline lines additionally use a legal sampleCount:1 pass after main resolve (see library Internals on GitHub). WebGPU only allows portable multisample counts of 1 or 4 — sampleCount: 2 is invalid and will fail validation (Invalid CommandBuffer). antialias is create-only. devicePixelRatio is a create-time policy (explicit freezes buffer + overlays; omitted tracks live window DPR on resize) — see top of this page.

CandlestickSeriesConfig

// Absolute HLC + companion mean line (recommended dual-series pattern)
series: [
  {
    type: 'errorBar',
    name: 'Assay ±SEM',
    data: { x: doses, y: means, high: highs, low: lows },
    itemStyle: { color: '#38bdf8', borderWidth: 2 },
    capWidth: '40%',
    errorMode: 'both',
    showCenter: true,
    symbolSize: 8,
  },
  {
    type: 'line',
    name: 'Mean',
    data: { x: doses, y: means },
    lineStyle: { color: '#38bdf8', width: 2 },
    sampling: 'none',
  },
]
// Relative SEM: data: { x, y: means, yError: sems }

Example: examples/error-bars/. Implementation: createErrorBarRenderer.ts, errorBar.wgsl, errorBarData.ts, errorBarGeometry.ts.

ImpulseSeriesConfig

Impulse / stem series (type: 'impulse') draws one vertical stem per sample from baseline → y — for event trains, DSP stems, and lollipop charts.

Not the same as:

• data
  same cartesian XY formats as line ({x,y}, tuples, interleaved).
• baseline?number
  (default 0): data-space floor of each stem. Non-finite → 0 + warn. Auto Y bounds include baseline when outside the data range.
• lineStyle?{ width?, opacity?, color? }
  stem stroke. Width default 2 CSS px (clamp ≤0 → 1). Color falls back to series.color → palette. Thickness is CSS px → domain X (same lesson as error bars / OHLC — not domain-X units as Y thickness).
• showMarker?boolean
  (default true): lollipop head at (x, y). Set false for pure stems.
• symbolSize?number
  (default 6): marker size (CSS px, scatter spirit).
• sampling
  'none' only. Other modes warn and are ignored (sparse event stems; no LTTB / GPU line decimation).
• Null / NaN
  skip stem for non-finite x/y. Zero-length (y ≈ baseline) skips the stem body but still draws the marker when enabled.
• Tooltip / hit-test
  stem + marker with CSS-px pad. TooltipParams: value: [x, y] plus optional baseline. Hit priority: pie → candle/ohlc → errorBar → impulse → nearest cartesian → heatmap.
• appendData
  same XY payloads as line; FIFO maxPoints supported.
• GPU
  instanced stems (+ optional markers) reusing error-bar instance layout; private pack dirty-gated on data identity.

series: [{
  type: 'impulse',
  name: 'Events',
  data: { x, y },
  baseline: 0,
  lineStyle: { width: 2, color: '#a78bfa' },
  showMarker: true,
  symbolSize: 6,
  sampling: 'none',
}]

Example: examples/impulse/. Step digital line: examples/step-line/. Implementation: createImpulseRenderer.ts, impulseGeometry.ts, stepGeometry.ts.

Step / impulse cheatsheet

PieSeriesConfig

• Non-cartesian. No x/y bounds or cartesian hit-test. Slice hit-test via findPieSlice. radius?, center?, startAngle?. Example: pie/.

Axis Configuration

• AxisConfig
  configuration for xAxis / yAxes. See types.ts.
• AxisType'value' | 'time' | 'category' | 'log'
  'value' | 'time' | 'category' | 'log'.
• Logarithmic axes (type: 'log')
  • Available on xAxis and each yAxis / yAxes[] independently.
  • logBase?number
    logarithm base (default 10). Must be finite, > 0, and ≠ 1; invalid values fall back to 10 with a dev warning.
  • Projection
    data stays in linear storage (DataStore / GPU buffers). Log is applied in series vertex shaders before the clip affine — toggling log does not force a full re-upload.
  • Ticks / grid
    major ticks at integer powers of the base (e.g. (10^{-2}, 10^{0}, 10^{3})) for the visible domain (updates on zoom/pan; not locked to full explicit min/max). When the window has few majors, intermediate ticks densify (e.g. 2×/5× within a decade). GPU grid lines for log axes are co-located with those ticks (not even data-space splits). Labels use a scientific/1eN hybrid by default; custom tickFormatter still receives data-space values (e.g. 1000, not 3).
  • Domain must be strictly positive
    auto-bounds ignore ≤0 samples; if no positive data exists the domain falls back to [1, 10] with a warning. Explicit min/max ≤ 0 are clamped using the smallest positive data value pd: prefer pd × 0.5, then floor to a power of logBase (base ** floor(log_b(pd × 0.5))), with a dev warning. Example (base 10): pd = 9 → half 4.5 → floored power 1.
  • Non-positive points
    treated as gaps on line/area (NaN packing path / VS discard) and omitted on scatter under log projection.
  • Area / bar baseline
    classic “fill to zero” is unsupported on log; baseline uses the positive axis min (or first major ≤ data min). Document that fill-to-zero is not available on log Y.
  • Sticky headroom
    on log axes is applied in log space (decade headroom).
  • Zoom
    start/end percents remain percent of data-space base domain (not log-percent).
  • No library UI log toggle
    config only (setOption({ yAxis: { type: 'log' } })). Examples may include demo chrome.
  • Showcase
    examples/log-axis-y/, log-axis-x/, log-axis-scatter/, log-axis-multi/, log-axis-compare/.
• Multiple Y-Axes
  • Instead of a single yAxis object, ChartGPU supports an array of Y axes via axes.y for independent scales (e.g. Price vs Volume).
  • Each axis in axes.y may specify an id: string (defaults: first axis "y", then "y1", …).
  • Series map to a specific axis via yAxis id in their config.
  • Axes can be positioned on the right using position: "right". Default position is "left", except for candle-primary charts (see below).
  • Dual Y may mix log + linear (e.g. log pressure + linear temperature). Horizontal grid follows the primary (first) Y axis ticks (log and linear value majors).
• Finance-primary layout defaults
  (when series[0].type === 'candlestick' or 'ohlc'):

  • Predicate
    only the first series type matters. Overlay lines as series[0] mean the chart is not candle-primary (set position: 'right' explicitly if needed). Helper: isCandlePrimaryChart(userOptions).
  • Y position
    the first Y axis defaults to position: 'right' when the user leaves position unset (yAxis or axes.y[0]). Secondary Y axes still default to 'left'. Explicit position always wins.

  • Soft grid gutters (per-key only for most cases — each of grid.left / grid.right is set only when that key is undefined on user options; 0 is preserved):

    Scenario	grid.left if unset	grid.right if unset
    Single candle, price on right	20	80
    Candle + volume (left Y remains)	60	80
    User set grid.left: 80 only	80 (kept)	70
    User set both margins (right ≥ 80 or 0)	unchanged	unchanged
    User set both with small right (e.g. right: 24) and a right Y	unchanged	floored to 80
    Non-candle-primary	60	20

  • Right-rail floor
    when candle-primary and any Y is on the right, a positive grid.right below 80 is raised to 80 so left-Y line-chart templates (left: 70, right: 24) do not clip tick labels or the last-price badge. Explicit right: 0 (full-bleed) and right ≥ 80 are unchanged.
  • Non-candle-primary charts keep the standard grid defaults and left Y.
  • Migration (P1 default badge)
    candle-primary charts also auto-enable priceLabel (last-price badge + price line) when priceLabel is omitted. This is a default visual change for existing candle consumers. Opt out with priceLabel: false. To restore a pre-upgrade left-axis look:

{
  yAxis: { type: 'value', position: 'left' },
  grid: { left: 70, right: 24 },
  series: [{ type: 'candlestick', data, priceLabel: false }],
}

• Recommended candle + volume dual-Y (or omit both gutters — dual-Y policy yields left 60 / right 80):

{
  grid: { left: 60, right: 80 },
  axes: {
    y: [
      { id: 'price', position: 'right', type: 'value', header: 'USDT' },
      { id: 'vol', position: 'left', type: 'value' },
    ],
  },
  series: [
    {
      type: 'candlestick',
      yAxis: 'price',
      data,
      // Optional: countdown needs intervalMs (and nowMs for simulated clocks)
      priceLabel: { intervalMs: 60_000 },
    },
    { type: 'bar', yAxis: 'vol', data: volumes },
  ],
}

• Explicit domains (override auto-bounds)
  • AxisConfig.min?: number / AxisConfig.max?: number
    when set, ChartGPU uses these explicit axis bounds and does not auto-derive bounds from data for that axis.
  • Precedence
    explicit min/max always override any auto-bounds behavior.
  • One-sided explicit
    if only min or only max is set, the other end is still data-derived; sticky auto-domain headroom (below) is disabled whenever either end is explicit so growBy padding never extends past a locked edge.
  • Log
    both ends must resolve to strictly positive values (see log policy above).
• Sticky auto-domain headroom (streaming / multi-chart)
  default motion:

  • When both ends of an axis are auto (no explicit min/max), ChartGPU uses a sticky domain: first establish matches the data extrema exactly (static column/mountain charts fill the plot).
  • Y: ~10% growBy headroom is added only when data breaches that domain (amortizes overlay rebuild under amplitude noise).
  • X: headroom is 0 so unbounded appendData tracks data max tightly and the series stays full plot width. Non-zero X pad previously left an empty right gutter that filled then re-expanded on every breach (visible as a grow/reset loop in examples like ultimate-benchmark streaming).
  • If the data min slides upward (FIFO/maxPoints drop-oldest), sticky follows the new min instead of freezing the historical origin. Sticky X is off entirely when autoScroll: true.
  • Cleared on setOption (including axes-only rewrites) and when any end becomes explicit.
  • Does not change sampling contracts (lttb stays lttb).
• Auto-range motion (AxisConfig.autoRange)
  opt-in continuous / animated rolling Y axes:

  • Y-only
    paint applies autoRange / growBy to Y axes. Values on xAxis are accepted by the option resolver but ignored at paint time (X keeps sticky headroom 0 + autoScroll skip).
  • autoRange?: 'sticky' | 'continuous' | 'animated' (default 'sticky'). Applies when both ends are free; any explicit min/max still disables pad past locked edges.

    • sticky
      current headroom hold-until-breach policy (safe multi-chart default).
    • continuous
      visible domain tracks data bounds every paint with optional padding (growBy).
    • animated
      tracks a target domain (same pad as continuous); paint domain lerps toward the target (time-based) so range motion is smooth.
  • growBy?number | [minEdge, maxEdge]
    pad as a fraction of data span for continuous/animated Y only (default ~5% per edge when omitted). Sticky ignores growBy and keeps internal ~10% Y / 0 X headroom.
  • Nice value ticks
    linear/value majors use a shared 1–2–5 × 10ⁿ ladder clamped to the visible domain. Category X uses equal index splits. Time and log generators stay authoritative for those axis types.
  • Tick-aligned grid
    primary Y majors drive horizontal grid lines; X tick values drive vertical grid (value, time, and log) — labels, GPU tick marks, and grid share one tick list per axis.
  • Demo
    examples/axis-streaming-smooth/ (autoRange: 'continuous', grid on, rising Y).
  • Example:

{
  yAxis: { type: 'value', autoRange: 'continuous', growBy: 0.05 },
  // or: autoRange: 'animated'
  series: [{ type: 'line', data }],
}

Tick Formatter Examples

// Duration formatting (seconds → human-readable)
yAxis: {
  tickFormatter: (seconds) => {
    const d = Math.floor(seconds / 86400);
    const h = Math.floor((seconds % 86400) / 3600);
    return d > 0 ? `${d}d ${h}h` : `${h}h`;
  }
}

// Percentage formatting (0–1 → 0%–100%)
yAxis: { tickFormatter: (v) => `${(v * 100).toFixed(0)}%` }

// Integer-only ticks (suppress fractional labels)
xAxis: { tickFormatter: (v) => Number.isInteger(v) ? v.toLocaleString() : null }

// Custom time axis formatting
xAxis: {
  type: 'time',
  tickFormatter: (ms) => new Date(ms).toLocaleDateString('de-DE')
}

// Append units
yAxis: { tickFormatter: (v) => `${v.toFixed(1)} ms` }

• xAxis.type'time' (timestamps)
  when xAxis.type === 'time', x-values are interpreted as timestamps in milliseconds since Unix epoch (the same unit accepted by new Date(ms)), including candlestick timestamp values. For GPU precision, ChartGPU may internally rebase large time x-values (e.g. epoch-ms domains) before uploading to Float32 vertex buffers; this is automatic and does not change your units. See the runtime axis label/tick logic in createRenderCoordinator.ts.
• Time x-axis tick labels (automatic tiers)
  when xAxis.type === 'time', x-axis tick labels are formatted based on the current visible x-range (after data zoom):

  Visible x-range (approx.)	Label format
  < 2 seconds	HH:mm:ss.SSS
  < 5 minutes	HH:mm:ss
  < 1 day	HH:mm
  1–7 days	MM/DD HH:mm
  ~1–12 weeks (or < ~3 months)	MM/DD
  ~3–12 months (≤ ~1 year)	MMM DD
  > ~1 year	YYYY/MM

  Notes: month/year thresholds are approximate (30d / 365d), and formatting uses the browser's Date semantics (local timezone). Sub-5-minute / sub-second tiers keep labels unique when deeply zoomed and update as you pan. Implementation: timeAxisUtils.ts (formatTimeTickValue); wired from createRenderCoordinatorImpl.ts (public shell: createRenderCoordinator.ts).

• Nice time tick positions (time x-axis only)
  for xAxis.type === 'time', tick values are snapped to a ladder of epoch-aligned nice steps (ms → s → min → h → day → week → ~month/~quarter/~year), not raw equal splits of dataMin→dataMax. Steps are absolute multiples of each ladder duration from Unix epoch (e.g. whole-hour UTC boundaries for hour steps)—not local midnights, week starts, or true calendar month boundaries. Label text still uses local Date formatting, so wall-clock labels can differ from the absolute grid depending on timezone offset. That still avoids awkward mid-interval times like 02:41 / 08:40 on a full-day view in favor of nice hour/day spacing. Non-time (value) axes still use evenly spaced linear ticks. See timeAxisUtils.ts.
• Adaptive tick count (overlap avoidance, time x-axis only)
  when xAxis.type === 'time', ChartGPU may vary tick density per render to avoid DOM label overlap. Density is step-wise, not an exact linear count: it tries denser nice-step sets first (target count in [1, 9]), and when a candidate set's labels overlap it may subsample that set (every 2nd / 3rd tick) before dropping to a coarser ladder target. The densest non-overlapping set is kept (minimum gap 6 CSS px); if measurement isn't available it falls back to a default-density nice tick set. GPU tick marks and DOM tick labels share the same computed tick values (nice time steps for time axes; linear domain splits for value axes). See timeAxisUtils.ts (computeAdaptiveTimeXAxisTicks), createRenderCoordinatorImpl.ts, and createAxisRenderer.ts.
• AxisConfig.name?string
  renders an axis title for cartesian charts when provided (and non-empty after trim()): x-axis titles are centered below x-axis tick labels, and y-axis titles are rotated (-90°) and placed left of y-axis tick labels (or (+90°) on the right rail); titles can be clipped if grid.bottom / grid.left / grid.right margins are too small. When dataZoom includes a slider (see below), ChartGPU reserves extra bottom space so the x-axis title remains visible above the slider overlay and is centered within the remaining space above the slider track. See createRenderCoordinatorImpl.ts (public shell: createRenderCoordinator.ts) and option resolution in OptionResolver.ts.
• AxisConfig.header?string
  optional non-rotated unit header at the top of a Y-axis rail (e.g. "USDT" for a quote currency). Independent of name — use header for short exchange-style unit labels and keep name for a longer rotated side title if needed. Applies to yAxis / axes.y only (ignored for xAxis). Place it with enough grid.top margin so it is not clipped. Rendered via the same axis text overlay as tick labels (bold, theme textColor / fontFamily).

// Exchange-style right price axis with unit header
yAxis: { type: 'value', header: 'USDT' } // candle-primary defaults position to 'right'

• Axis title styling
  titles are rendered via the internal DOM text overlay and use the resolved theme's textColor and fontFamily with slightly larger, bold text (label elements also set dir='auto').

Grid Lines Configuration

• ChartGPUOptions.gridLines?GridLinesConfig
  optional configuration for the background grid lines drawn inside the plot area. See GridLinesConfig and defaults.ts.
• What grid lines are
  grid lines are evenly-spaced lines drawn across the plot grid to aid visual reading of values. They are not aligned to axis ticks — they are distributed uniformly across the horizontal and vertical extent of the plot area. Lines are rendered via a WebGPU line-list primitive, so they are always 1 device pixel wide (this is a WebGPU limitation; line width is not configurable).
• Default behavior
  when gridLines is omitted, grid lines are shown using the theme's gridLineColor (dark theme: rgba(255,255,255,0.1); light theme: rgba(0,0,0,0.1)) with 5 horizontal and 6 vertical lines. See defaultGridLines and createGridRenderer.ts.

GridLinesConfig

Top-level grid lines configuration. See types.ts.

• show?boolean
  global toggle for all grid lines. When false, no grid lines are drawn. Default: true.
• color?string
  CSS color string for all grid lines. Can be overridden per-direction via horizontal.color or vertical.color. Falls back to theme.gridLineColor when not specified. Expected formats: #rgb, #rrggbb, #rrggbbaa, rgb(r,g,b), rgba(r,g,b,a).
• opacity?number
  global opacity multiplier for grid lines (0–1). This multiplies the alpha channel of the resolved color (including per-direction overrides). Default: 1.
• horizontal?boolean | GridLinesDirectionConfig
  horizontal grid lines (constant-Y, spanning left→right). Accepts a boolean shorthand (true = show with defaults, false = hide) or a detailed GridLinesDirectionConfig. Default: { show: true, count: 5 }.
• vertical?boolean | GridLinesDirectionConfig
  vertical grid lines (constant-X, spanning top→bottom). Accepts a boolean shorthand (true = show with defaults, false = hide) or a detailed GridLinesDirectionConfig. Default: { show: true, count: 6 }.

GridLinesDirectionConfig

Per-direction (horizontal or vertical) grid line settings. See types.ts.

• show?boolean
  whether to show grid lines in this direction. When false, no lines are drawn regardless of count. Default: true.
• count?number
  number of evenly-spaced grid lines. Default: 5 (horizontal), 6 (vertical).
• color?string
  CSS color string for lines in this direction. Overrides the top-level gridLines.color and theme.gridLineColor.

Grid Lines Examples

gridLines: { show: false }  // hide all
gridLines: { horizontal: true, vertical: false }  // horizontal only
gridLines: { color: 'rgba(100,100,255,0.2)', horizontal: { count: 8 }, vertical: { count: 10 } }

Data Zoom Configuration

• ChartGPUOptions.dataZoom?ReadonlyArray<DataZoomConfig>
  optional data-zoom configuration list. See ChartGPUOptions and DataZoomConfig.
• Runtime behavior (current)
  data zoom controls a shared percent-space zoom window { start, end } in ([0, 100]) that is applied to the effective x-domain for both rendering and pointer interaction. See the x-domain application in createRenderCoordinator.ts and percent-space semantics in createZoomState.ts.

  • Span constraints (min/max)
    ChartGPU clamps the zoom window span using DataZoomConfig.minSpan / DataZoomConfig.maxSpan at runtime (applies consistently to inside zoom, slider UI, and programmatic APIs), and re-applies constraints when options/data change (e.g. on setOption(...) and streaming appendData(...)). See createZoomState.ts and coordinator wiring in createRenderCoordinator.ts.

    • When minSpan / maxSpan are omitted, ChartGPU uses a dataset-aware default minimum span for xAxis.type: 'value' | 'time', targeting roughly one data interval: approximately (100/(N-1))% where (N) is the largest raw point count across non-pie cartesian series (raw/unsampled data; updates as points are appended). When there is insufficient data to infer an interval ((N < 2)), ChartGPU falls back to 0.5% to keep the UI usable. See createRenderCoordinator.ts.
    • For xAxis.type: 'category', no dataset-aware default is currently applied; use minSpan explicitly if you need deeper zoom for very large category counts.
  • Zoom-aware sampling (cartesian)
    when a cartesian series has sampling enabled, ChartGPU resamples from raw (unsampled) series data over the current visible x-range. Zoom changes schedule an honest re-sample on the next flush/frame (period=1 — not a multi-frame slice of prior full-span samples); a ±10% buffer zone reduces re-work during small pans. GPU-decimation series keep full raw and scope via visible indices. See createRenderCoordinator.ts and performance — zoom-aware resampling.
  • Inside zoom
    when ChartGPUOptions.dataZoom includes { type: 'inside' }, ChartGPU enables an internal wheel/drag interaction. See createRenderCoordinator.ts and createInsideZoom.ts.
  • Zoom gesture
    mouse wheel zoom, centered on the current cursor x-position (only when the pointer is inside the plot grid).
  • Pan gesture
    shift+left-drag or middle-mouse drag pans left/right (only when the pointer is inside the plot grid).
  • Scope
    the zoom window is applied to the x-domain; the y-domain is derived from data unless you set explicit yAxis.min/yAxis.max.

    • Default behavior
      during x-zoom, yAxis.autoBounds: 'visible' derives y-bounds from the visible x-range.
    • Opt out
      set yAxis.autoBounds: 'global' to keep y-bounds derived from the full dataset, or set explicit yAxis.min/yAxis.max.
  • Grid-only
    input is ignored outside the plot grid (respects grid margins).
  • Slider UI
    when ChartGPUOptions.dataZoom includes { type: 'slider' }, ChartGPU mounts a slider-style UI that manipulates the same percent zoom window. ChartGPU also reserves 40 CSS px of additional bottom plot space so x-axis tick labels and the x-axis title remain visible above the slider overlay (you generally should not need to manually “make room” by increasing grid.bottom). See ChartGPU.ts, option resolution in OptionResolver.ts, and the internal UI helper createDataZoomSlider.ts.
  • Coexistence
    multiple data-zoom configs can coexist (e.g. inside + slider) and drive the same x-zoom window.
  • Config fields
    start / end are used as the initial percent window (defaulting to 0 / 100 when omitted). minSpan / maxSpan are applied to the runtime clamping behavior (see above). xAxisIndex is currently accepted by the type but only xAxisIndex: 0 is supported by the runtime zoom path.
• DataZoomConfig
  data zoom configuration type. See DataZoomConfig.

  • type: 'inside' | 'slider'
  • xAxisIndex?: number
  • start?: number: start percent in ([0, 100])
  • end?: number: end percent in ([0, 100])
  • minSpan?: number
  • maxSpan?: number

Tooltip Configuration

• tooltip?TooltipConfig
  show, trigger: 'item' | 'axis', formatter. Enabled by default.
• TooltipParams.value
  [x, y] (cartesian/pie), [timestamp, open, close, low, high] (candlestick). Distinguish via value.length.
• Safety
  tooltip uses innerHTML — return trusted/sanitized strings only.
• Helpers
  formatTooltipItem, formatTooltipAxis in formatTooltip.ts. Examples: basic-line/, interactive/.

Animation Configuration

• ChartGPUOptions.animation?AnimationConfig | boolean
  optional animation configuration.

  • Default
    when omitted, animation is enabled with defaults (equivalent to true). See OptionResolver.ts.
  • Disablement
    set to false to disable all animation.
  • Defaults
    when enabled, AnimationConfig.duration defaults to 300ms when omitted.
• AnimationConfig
  supports optional duration?: number (ms), easing?: 'linear' | 'cubicOut' | 'cubicInOut' | 'bounceOut', and delay?: number (ms). See types.ts.

  • Built-in easing implementations (internal): see easing.ts and the name→function helper getEasing(...).
• Initial-load intro animation
  when animation is enabled, series marks animate on first render. Axes, grid lines, and labels render immediately (not animated). Per-series effects: line/area series reveal left-to-right via plot scissor; bar series grow upward from baseline; pie slices expand radius; scatter points fade in. The intro animation requests frames internally during the transition. See createRenderCoordinator.ts. Streaming demos may prefer disabling animation (animation: false).
• Data update transition animation
  when animation is enabled, subsequent calls to ChartGPUInstance.setOption(...) (and the internal RenderCoordinator.setOptions(...)) that change series data can animate transitions after the initial render has occurred. See the internal implementation in createRenderCoordinator.ts and the visual acceptance examples in examples/data-update-animation/ (bar + line + pie) and examples/multi-series-animation/ (area + bar + line + scatter on a single chart, with configurable line width).

  • When it triggers (high-level)
    a post-initial-render options update that changes series[i].data (cartesian and pie), with ChartGPUOptions.animation enabled.
  • What animates (high-level)
    • Cartesian series
      y-values interpolate by index while x-values come from the new series (index-aligned). Bars morph via the same y interpolation.
    • Pie series
      slice values interpolate by index, producing animated angle changes.
    • Derived domains/scales
      when auto-derived axis domains change (from updated data), the domain values animate to the new extents.
  • Constraints / notes (high-level)
    • Match-by-index
      interpolation is index-based; length changes and type/shape mismatches may skip interpolation and apply the new series immediately.
    • Large-series safeguard
      very large series may skip per-point interpolation while still animating derived domains (internal safeguard).
    • Mid-flight updates
      a new setOption(...) during an active transition rebases the transition from the current displayed state (avoids a visual jump).

OHLC Data Types

OHLCDataPoint (public export): exported from the public entrypoint src/index.ts and defined in types.ts. Represents a candlestick data point as either a tuple (readonly [timestamp, open, close, low, high], ECharts order) or an object (Readonly<{ timestamp, open, close, low, high }>). Used by CandlestickSeriesConfig. Both candlestick rendering and OHLC sampling are fully functional (see CandlestickSeriesConfig above).

candlestickDefaults (public export): exported from the public entrypoint src/index.ts and defined in defaults.ts. Provides default configuration values for candlestick series. Both candlestick rendering and OHLC sampling are fully functional (see CandlestickSeriesConfig above).

Default Options

Default chart options used as a baseline for resolution.

See defaults.ts for the defaults (including grid, grid lines, palette, and axis defaults).

Behavior notes (essential):

• Default grid
  left: 60, right: 20, top: 40, bottom: 40 (non-candle-primary). Candle-primary soft gutters: see Candle-primary layout defaults under Axis Configuration (right: 80; left: 20 or 60 depending on left Y axes).
• Palette / series colors
  ChartGPUOptions.palette acts as an override for the resolved theme palette (resolvedOptions.theme.colorPalette). When series[i].color is missing, the default series color comes from resolvedOptions.theme.colorPalette[i % ...]. For backward compatibility, the resolved palette is the resolved theme palette. See resolveOptions and ThemeConfig.
• Line series stroke color precedence
  for type: 'line', effective stroke color follows: lineStyle.color → series.color → theme palette. See resolveOptions.
• Line series fill color precedence
  for type: 'line' with areaStyle, effective fill color follows: areaStyle.color → resolved stroke color (from above precedence). See resolveOptions.
• Area series fill color precedence
  for type: 'area', effective fill color follows: areaStyle.color → series.color → theme palette. See resolveOptions.
• Axis ticks
  AxisConfig.tickLength controls tick length in CSS pixels (default: 6)

resolveOptions

resolveOptions(userOptions?: ChartGPUOptions)
// Alias:
OptionResolver.resolve(userOptions?: ChartGPUOptions)

Resolves user options against defaults by deep-merging user-provided values with defaults and returning a resolved options object.

See OptionResolver.ts for the resolver API and resolved option types.

Behavior notes (essential):

• Theme input
  ChartGPUOptions.theme accepts 'dark' | 'light' or a ThemeConfig; the resolved theme is always a concrete ThemeConfig. See ChartGPUOptions and resolveOptions.
• Default theme
  when theme is omitted, the resolved theme defaults to 'dark' via getTheme (preset: darkTheme).
• Theme name resolutionresolveOptions({ theme: 'light' })
  resolves theme to the light preset config (see lightTheme).
• Palette override
  when ChartGPUOptions.palette is provided (non-empty), it overrides the resolved theme palette (resolvedOptions.theme.colorPalette). The resolved palette mirrors the resolved theme palette for backward compatibility. See resolveOptions.

Performance Metrics Types

• PerformanceMetrics
  fps, frameTimeStats (min/max/avg/p50/p95/p99), gpuTiming, memory, frameDrops, totalFrames, elapsedTime. Returns null before first frame.
• PerformanceCapabilities
  gpuTimingSupported, highResTimerSupported, performanceMetricsSupported.
• Branded types
  ExactFPS, Milliseconds, Bytes. See types.ts.

API reference for the linked @chartgpu/chartgpu package (v0.4.0). Source on GitHub.