Octane Adapter

@tanstack/octane-charts is the native TSRX lifecycle and SSR adapter around @tanstack/charts. Definitions, scenes, responsive layout, rendering, interaction, and animation remain framework-neutral.

Public exports#

export { Chart } from '@tanstack/octane-charts'

export type {
  ChartCommonProps,
  ChartProps,
  ChartTooltipBodyRenderContext,
  ChartDefinition,
  ChartPoint,
} from '@tanstack/octane-charts'

Choose Canvas or an application-supplied renderer through an explicit subpath:

import { Chart as CanvasChart } from '@tanstack/octane-charts/canvas'
import { Chart as RendererChart } from '@tanstack/octane-charts/core'

The default Chart remains SVG-based. CanvasChart selects the optional built-in renderer; RendererChart requires a renderer prop.

The package export map supplies a browser build for browser bundlers and a separate Node build for the node condition.

Render lifecycle#

The adapter creates one ChartRuntime for each component instance and asks the selected renderer for initial markup in TSRX. After layout:

1. useLayoutEffect mounts the shared DOM host into the existing chart surface
2. the initial runtime is passed through
3. a later layout effect forwards memoized host options
4. subsequent Octane updates call host.update; a new definition identity rebuilds the scene
5. cleanup destroys the host and all browser-owned behavior

The inner chart surface is memoized after its first output. The shared host paints later scenes directly into the selected surface. Memoize definitions that capture component values with useMemo; module-scope definitions need no component memoization.

SSR and hydration#

The default Node target renders the complete .ts-chart-host, .ts-chart-surface, and accessible SVG at initialWidth. The browser target hydrates the same structure before mounting the host.

The Canvas entry renders a deterministic named root and two aria-hidden canvases on the server. It paints no server pixels. The browser adopts the elements, paints after mount, and attaches the same focus, keyboard, tooltip, and selection host.

Keep data, definitions, scale domains, custom renderers, and dimensions deterministic between server and browser. The adapter generates a sanitized resource prefix from Octane's useId() when idPrefix is absent.

tabIndex defaults to 0 on both targets. keyboard: false forces it to -1.

Pass renderChartSvgWithResources on both targets for gradients and clipping; see Rendering and export.

Sizing and layout#

The rendered structure is:

.ts-chart-host
  .ts-chart-surface
    svg.ts-chart | div.ts-chart-canvas

The outer host uses position: relative.

initialWidth defaults to 640. A fixed height takes precedence over aspectRatio; nonpositive and nonfinite ratios fall back to the default height. Responsive measurement and inherited font relayout are shared with the vanilla DOM host.

class and style#

Octane-specific presentation props apply to the outer host:

<Chart
  definition={definition}
  ariaLabel="Revenue"
  class="dashboard-chart"
  style={{
    minHeight: 240,
    color: 'var(--foreground)',
  }}
/>

• class is appended after ts-chart-host.
• style is Record<string, string | number | undefined>.
• styles are spread after adapter sizing, so they can override position, width, height, or aspect ratio.

Do not conflict a fixed width prop with style.width. The style changes the outer CSS box while the prop continues to lock scene measurement.

The core renderer's className option applies to a directly rendered surface, not the Octane outer host.

Definition and option identity#

Keep fixed definitions outside component execution. Keep one dynamic definition stable until a captured application value changes.

The adapter memoizes host options from semantic props. Callback functions are held in refs, so changing only a callback does not rebuild the option object and the live wrapper still calls the latest function.

Definition identity is core behavior; see Chart Definition API.

Tooltip body composition#

renderTooltipBody portals Octane output into the core-owned tooltip body. Its context contains points, content, defaultBody, pinned, and dismiss. Include defaultBody to retain native rows and swatches. The shared host owns focus, placement, portaling, inert transient state, pinning, and dismissal; Octane owns the returned component lifecycle.

Core boundary#

The adapter does not redefine chart grammar or data algorithms. Read Scales and D3 for injected primitives and the core API reference for marks, interaction, renderers, and extension contracts.