| title | Interactive Charts |
|---|---|
| description | Choose native focus or controlled application interactions for pinned detail, scrolling, zooming, and editing. |
Interaction should help the reader inspect, navigate, select, or edit semantic data. It should not turn a chart into a second application state system.
TanStack Charts owns nearest-point focus, grouped focus, keyboard point navigation, point selection callbacks, and native structured tooltips. The application owns interactions that change a domain, viewport, persistent selection, or product record.
| Reader task | Start with |
|---|---|
| Inspect one point or a same-x group | Native chart focus and tooltip |
| Keep rich framework detail open, including another chart | Pinned composed tooltip body |
| Navigate a wide schedule without changing its semantic scale | Native horizontal scrolling |
| Crop and pan a continuous domain | Controlled zoom and viewport state |
| Edit an interval or record | Controlled direct manipulation plus form input |
Interactions and Selections defines the controlled gesture loop. Tooltips and Focus defines the native inspection path.
A rich tooltip can compose the native rows with framework UI, including a second chart. Hover remains transient; click or keyboard activation pins the surface before it accepts pointer input.
<iframe src="https://tanstack.com/charts/catalog/embed/84-pinned-nested-chart-tooltip/?theme=system&height=500" title="Pinned rich tooltip containing a nested detail chart" loading="lazy" width="100%" height="500" style="width:100%;height:500px;border:0;" ></iframe>The embedded framework-neutral case uses a fully application-owned surface.
Use the adapter's tooltip-body composition surface and include defaultBody
to retain native rows and swatches. A grouped parent can pass points
directly into a pie definition, placing the series comparison beside the rows
in both transient and pinned states. The transient body is inert; gate controls
on pinned. The nested chart receives its own accessible label, definition,
runtime, and framework cleanup.
Set definition tooltip.portal: true to escape clipped ancestors and use
viewport collision handling. Move focus intentionally when the body contains
controls, preserve Escape, and wire a close button to dismiss.
Native horizontal scrolling is often better than zoom for resource lanes. It preserves a stable time scale and gives the browser proven wheel, touch, and keyboard behavior.
<iframe src="https://tanstack.com/charts/catalog/embed/85-scrollable-resource-lanes/?theme=system&height=480" title="Horizontally scrollable resource timeline with fixed lane labels" loading="lazy" width="100%" height="480" style="width:100%;height:480px;border:0;" ></iframe>Keep lane labels in a fixed rail and place the timeline in the scroll region. Preserve lane order, task keys, scroll position, and viewport-relative geometry across data updates. Do not capture vertical page scrolling when the timeline only needs horizontal movement.
Use Layout, Axes, and Coordinates to align labels and the plotted region.
Zooming changes an explicit semantic domain. Wheel, drag, touch, keyboard, and reset controls should all update the same start and end values.
<iframe src="https://tanstack.com/charts/catalog/embed/90-zoomable-time-window/?theme=system&height=480" title="Controlled time-domain wheel zoom and pan with keyboard and reset controls" loading="lazy" width="100%" height="480" style="width:100%;height:480px;border:0;" ></iframe>Define:
- Full-domain limits
- Minimum and maximum span
- Pointer anchor behavior
- Pan increments
- Wheel activation and normalization
- Touch cancellation
- Keyboard equivalents
- Reset behavior
Store the resulting domain in application state and pass it into the chart's configured scale. Preserve that domain when data values update unless product policy explicitly follows the latest point.
An editable timeline combines direct manipulation with native semantic controls. The chart renders the current record; application validation decides which edit can commit.
<iframe src="https://tanstack.com/charts/catalog/embed/92-editable-event-range/?theme=system&height=500" title="Editable scheduled event range with drag, keyboard, and date controls" loading="lazy" width="100%" height="500" style="width:100%;height:500px;border:0;" ></iframe>A complete editor should:
- Preserve the event's stable ID, start, and lane while its end changes.
- Clamp the end after the start.
- Support pointer cancellation and rollback.
- Offer keyboard-adjustable handles with adequate hit targets.
- Provide a native date or range input.
- Announce the current duration and validation state.
- Keep color-independent event labels visible.
Do not mutate a rectangle and treat that painted geometry as the saved record. Update application state, validate it, and let the next definition produce the scene.
Application-owned interaction state should be semantic:
- Date or numeric domain
- Selected row ID
- Start and end values
- Scroll offset
- Playback index
- Pinned datum key
Pixel geometry is derived from scene.chart and copied configured scales on
each render. This keeps state valid after responsive layout, font changes, and
server hydration.
Controllers and overlays may install pointer capture, event listeners, observers, nested hosts, and animation frames. Tear down every resource when the chart unmounts or ownership changes.
- Pointer, keyboard, and touch reach equivalent semantic outcomes.
- Focus indicators and controls remain visible and contained.
- Wheel handling does not unexpectedly trap page scrolling.
- Dragging has commit, cancel, clamp, and out-of-bounds behavior.
- Selection and viewport survive data and size updates.
- Reset behavior is explicit.
- Native chart focus is disabled only when another complete interaction owns the surface.
- Rich overlays and nested charts have independent accessibility and cleanup.
- Interaction state is tested as values, not only screenshots or DOM order.
Use Testing and Debugging for behavior scenarios and Accessibility for equivalent input paths.