Navigation and Accessibility

Use navigation to inspect a busy chart without changing the report. Zoom and pan change the visible portion; the legend identifies series; tooltips describe an individual value.

Try a legend entry, then inspect a mark with the keyboard. Choose Data for the current chart values in a keyboard-operable table. Navigation support depends on chart type and renderer.

Interactive example

Tooltips and keyboard access

Example for Tooltips and keyboard access

Change the visible category or time window, then reset the chart navigation.

The example loads when visible.

Reset

Use the example selector to compare Zoom and pan, Shared tooltip and crosshair, and Keyboard and selection. These are separate ways to inspect the same report; none edits the source records.

Zoom, pan, and the navigator

Navigation controls share one persisted category/time viewport (viewport.x). They change the visible window while retaining the complete chart dataset, Pivot filters, and semantic selection. Payload limits still apply to the complete dataset.

The built-in renderer supports category navigation for line and area charts (including smooth, stepped, stacked, and 100% stacked variants), grouped, stacked, and 100% stacked columns and bars, plus annotated time series, small multiples, column-line, and area-line. Horizontal bars navigate along their vertical category axis; their navigator remains horizontal. Explicit zoom, navigator, or viewport settings replace automatic dense category scrolling while active. The ordinary line, area, column, and bar types retain a category axis; time navigation remains available on annotated time series, small multiples, and the two combination types. Check the chart definition’s navigation capability and the configured renderer’s capabilities.navigation before offering custom controls. Unsupported authored settings are rejected.

await chart.update({
  navigation: {
    enabled: true,
    navigator: true,
    crosshair: true,
    tooltipMode: 'shared',
  },
  viewport: {
    x: { scale: 'category', startId: firstCategory.id, endId: lastCategory.id },
  },
});

// Restore the full X domain, retaining navigation controls.
await chart.update({ viewport: {} });

For a time axis, use absolute UTC epoch milliseconds within the supported date range:

await chart.update({
  axes: { x: { scale: 'time' } },
  viewport: { x: { scale: 'time', min: Date.UTC(2026, 0, 1), max: Date.UTC(2026, 2, 1) } },
});

The viewport scale must match the chart’s category/time axis policy. Both navigation and viewport use replacement updates: omit them to preserve their values, or pass {} to reset them. Navigation is opt-in; it does not change the default interaction mode.

With navigation enabled, wheel input zooms around the pointer, dragging pans the window, and touch supports category-axis pan and pinch zoom. Horizontal bars pan vertically and leave horizontal touch scrolling available; other charts pan horizontally and leave vertical touch scrolling available. A claimed drag suppresses its activation click; ordinary clicks keep the configured Drill, Select, Filter, or Event behavior. Escape cancels an active gesture.

The navigator’s start and end handles resize the same window; dragging its selected band pans it. Focus a handle or the band to use arrow keys, with Shift for a larger step and Home/End for a boundary. Separate zoom, pan, and reset buttons support keyboard operation without changing the arrow-key navigation of chart observations.

Category windows store semantic category IDs. Reordering resolves the inclusive interval between the current positions of both endpoints. If either endpoint disappears, the authored window remains dormant and the full domain is shown until both return. Time windows retain their absolute bounds; a window outside the current domain displays an empty plot with a reset action.

Refresh, unlink, relink, and saved-state restore retain the viewport when the semantic scope survives. Successful drill navigation or fallback to a valid ancestor scope resets it; failed navigation retains it. The automatic Y domain continues to use the full dataset, so panning does not change the apparent magnitude of values. Explicit Y bounds remain authoritative.

Crosshair and shared tooltips

navigation.crosshair follows the nearest visible category. With tooltipMode: 'shared', the existing tooltip card shows the active series for that category, including missing values and their display formatting. Matching uses category identity, so identical labels do not merge distinct members. Crosshair and shared tooltip state is transient and does not select, filter, drill, or broadcast highlighting to another chart.

Shared cards show up to 20 series and announce the omitted count. Custom tooltip formatters retain the existing primary datum context and receive optional sharedItems and omittedSharedItemCount; each shared item includes its original category/series index, value, display value, color, and authored axis unit. Keyboard focus follows the focused member, including distinct categories with the same timestamp. Pointer lookup uses a deterministic member for tied times and can inspect a visible category omitted by dense mark sampling.

Legend focus and visibility

Series legends are keyboard-accessible guides. By default, activating a legend item focuses that series, emphasizes matching marks, and mutes the others. Activating it again or selecting the chart background clears the focus. When a dense legend cannot fit, it shows a deterministic subset and a localized overflow count.

On charts supporting independent series visibility, set presentation.legendAction: 'toggleVisibility' to persist show/hide changes instead. Enter, Space, and pointer activation share the same action. Hidden series remain available for restoration; the canonical dataset and shared Pivot remain unchanged. The Display controls provide the full series list when the SVG legend overflows.

Read a chart value

Interactive marks use an application-owned tooltip card rather than native SVG title text. The default tooltip includes:

• the complete category path;
• series identity and formatted value;
• the resolved mark color;
• X, Y, and size rows for relationship charts;
• a drill hint when the datum has children.

Pointer tooltips stay inside the viewport. Keyboard focus opens the same card immediately and connects it with aria-describedby. Escape closes the tooltip without closing the chart dialog; selection modes also clear the selection, or request clearing in application-controlled Event mode. Gallery previews intentionally do not create tooltips.

Keyboard and accessibility

• The modeless dialog has a stable accessible name and restores focus when it closes. Tab can leave the chart to reach the grid. A menu or chart control that handles Escape keeps the outer dialog open.
• Gallery tabs, cards, breadcrumbs, legend items, chart marks, export actions, and the data table are keyboard operable.
• Marks have localized accessible names built from category, series, formatted value, relationship channels, and drillability.
• View data uses a read-only RevoGrid with a descriptive label, keyboard sorting, cell selection, and sort announcements.
• Status regions announce loading, drill success, failure, and data-table sort changes without replacing visible content.

Charts use one Tab stop for observation and aggregate inspection at every dataset size. Tab and Shift+Tab enter or leave inspection; arrow keys move between displayed targets, and Home/End reach the first/last. Enter or Space activates a real datum according to the interaction mode. Aggregate bins, analytical overlays, forecasts and synthetic Others are inspection-only; activating them never selects a representative source observation. Focus follows a retained observation through updates.

For the facts behind a selected observation, enable the shared underlying-records action. It uses Pivot’s existing paginated drillthrough API, rather than treating the chart’s aggregated data table as a list of source transactions.

Aggregate tooltips use localized inspection text. They do not call the datum tooltip formatter, whose context requires an individual category and series. The range-interval chart’s mean across several measure values is also an inspection target, rather than a cell belonging to one of those measures. Box and violin descriptions include their distribution statistics and retain drill hints where applicable. A precomputed summary without a mean does not announce an estimated mean.

Every chart provides a localized description of its data dimensions and actual inspection targets. Annotated time series and small multiples also describe finite source and displayed observations and sampling omissions. Navigation visits displayed targets; sampling never creates additional observations. Redraws preserve the focused semantic datum where possible, use a nearby displayed datum when it disappears, and leave focus outside the chart untouched. Empty charts have no observation navigation instructions, and gallery previews remain decorative.

Provide additional context with presentation.description, a plain-text string of up to 4096 UTF-16 code units. It is saved with the chart and linked to the chart’s accessible description. An empty string clears it; an omitted or undefined update preserves it. Description edits do not reload provider data.

The existing highContrast and highContrastDark themes are available alongside the other chart themes. Forced-color styling preserves focus and selected-control boundaries. Use supported marker shapes, line dashes, or member patterns when series need differentiation beyond color, and Data to inspect exact values in a table.

Drill and interaction events

Event	Purpose
pivot-chart-node-click	Reports the activated semantic datum and its paths/measure when no automatic drill target exists.
pivot-chart-before-selection	Cancelable proposal before a selection commit.
pivot-chart-selection-changed	Reports committed semantic selection.
pivot-chart-selection-request	Delegates Event-mode selection to the application.
pivot-chart-selection-error	Reports a failed selection/filter transition.
pivot-chart-before-drill	Cancelable event before a drill is committed.
pivot-chart-drill-start	Announces a pending drill frame.
pivot-chart-drilled	Supplies the committed model and dataset.
pivot-chart-drill-error	Reports the failed transition and error.
pivot-chart-drill-reset	Reports a successful reset to root.
pivot-chart-drill-sync	Delegates pivot, both, or event synchronization.

Event payloads clone JSON-safe semantic state. See Headless API and persistence for the full lifecycle event list.

Next steps

Continue with appearance, controls and localization and exporting.