Focus Guide Marks

focusGuideX and focusGuideY render ordinary scene nodes only for the active focus target. Import them from the exact optional subpath:

For an unsnapped x/y value pair with no datum focus target, use continuousCursor instead.

import { focusGuideX } from '@tanstack/charts/focus/guide'

focusGuideX(rows, {
  id: 'cursor',
  x: 'period',
  y: 'value',
  z: 'series',
  key: 'id',
  yRule: {},
  marker: {},
  xLabel: { format: (period) => period },
  yLabel: { format: (value) => String(value) },
  motion: {
    transition: { type: 'spring', stiffness: 240, damping: 22 },
  },
})

focusGuideX enables the vertical x rule by default. focusGuideY enables the horizontal y rule. Configure both rules on either mark for a crosshair.

function focusGuideX<TDatum>(
  source: Iterable<TDatum>,
  options: FocusGuideOptions<TDatum>,
): ChartMark<TDatum>

function focusGuideY<TDatum>(
  source: Iterable<TDatum>,
  options: FocusGuideOptions<TDatum>,
): ChartMark<TDatum>

Options#

Rule options provide stroke, strokeOpacity, strokeWidth, strokeDasharray, and lineCap. Marker options provide radius, fill, fillOpacity, stroke, strokeOpacity, and strokeWidth. Paint and numeric rule or marker values may be datum visual channels.

Label options provide format, side, offset, paddingX, paddingY, radius, background, color, stroke, strokeWidth, fontSize, and fontWeight. A formatter receives the typed semantic value and a FocusGuideLabelFormatContext containing { point }, the active ChartPoint and its original datum reference.

Focus and motion#

Guide candidates participate in scale inference but do not enter ChartScene.points, pointer hit testing, callbacks, or tooltip rows. Focus resolves the selected candidate under stable structural keys. The first target enters at its final coordinate, later targets update the same rule, marker, and label nodes, and clearing focus exits those nodes.

Primary matching uses the original object reference, or the primitive value plus source position for primitive rows. Candidate ownership is structural; keys such as a and a:point remain distinct rather than being interpreted as a hierarchy.

Static SVG, Canvas, and native surfaces snap to the resolved focus target. The optional @tanstack/charts/motion SVG renderer applies motion, preserves spring velocity through rapid retargets, and handles reduced motion and teardown. A focus guide composes with the default focus ring; set focusRing: false only when its marker replaces that indicator.

whenFocused(mark, { retarget: true }) exposes the same structural behavior for custom compositions. Normal whenFocused marks keep their existing pre-rendered visibility behavior when retarget is omitted.