GraphicWalker

GraphicWalker is the primary component that provides a full interactive data exploration interface with drag-and-drop chart building, field management, and multiple chart tabs.

import { GraphicWalker } from '@kanaries/graphic-walker';

Props

Data Props

Prop	Type	Required	Description
`data`	`Record<string, any>[]`	Yes*	Array of data records. Used for client-side computation.
`fields`	`IMutField[]`	Yes	Field definitions describing each column in your data.
`computation`	`IComputationFunction`	Yes*	Server-side computation function. Alternative to `data`.
`computationTimeout`	`number`	No	Timeout in ms for computation requests.

*Provide either data (client-side) or computation (server-side), not both.

Chart Configuration Props

Prop	Type	Default	Description
`chart`	`IChart[]`	`undefined`	Pre-configured chart specifications to load.
`defaultConfig`	`{ config?: Partial<IVisualConfigNew>; layout?: Partial<IVisualLayout> }`	`undefined`	Default config applied to new charts.
`defaultRenderer`	`'vega-lite' \| 'observable-plot'`	`'vega-lite'`	Default rendering engine for new charts.

Appearance Props

Prop	Type	Default	Description
`appearance`	`'media' \| 'light' \| 'dark'`	`'media'`	Dark mode setting. `'media'` follows system preference.
`vizThemeConfig`	`IThemeKey \| GWGlobalConfig`	`undefined`	Chart rendering theme. Built-in options: `'vega'`, `'g2'`, `'streamlit'`.
`uiTheme`	`IUIThemeConfig`	`undefined`	Custom UI color scheme for light and dark modes.

UI Control Props

Prop	Type	Default	Description
`hideChartNav`	`boolean`	`false`	Hide the chart tab navigation, restricting to a single chart.
`hideSegmentNav`	`boolean`	`false`	Hide the data/visualization segment navigation.
`hideProfiling`	`boolean`	`false`	Hide field profiling (distribution previews).
`toolbar`	`{ extra?: ToolbarItemProps[]; exclude?: string[] }`	`undefined`	Customize the toolbar — add extra buttons or exclude built-in ones.

Data Features Props

Prop	Type	Default	Description
`scales`	`IChannelScales`	`undefined`	Custom scale configurations for visual channels.
`geographicData`	`IGeographicData & { key: string }`	`undefined`	GeoJSON/TopoJSON data for geographic visualizations.
`geoList`	`IGeoDataItem[]`	`undefined`	List of geographic datasets available for selection.
`experimentalFeatures`	`{ computedField?: boolean }`	`undefined`	Enable experimental features like computed fields.

i18n Props

Prop	Type	Default	Description
`i18nLang`	`string`	`undefined`	Language code (e.g., `'en-US'`, `'zh-CN'`, `'ja-JP'`).
`i18nResources`	`Record<string, Record<string, string>>`	`undefined`	Custom translation resources.

Ref & State Props

Prop	Type	Description
`ref`	`React.Ref<IGWHandler>`	Ref to access the handler API (export charts, navigate tabs, etc.).
`storeRef`	`React.RefObject<CommonStore>`	Ref to the internal state store.
`keepAlive`	`boolean \| string`	Keep component state alive when unmounted. Pass a string as a unique key for multiple instances.
`onMetaChange`	`(fid: string, meta: Partial<IMutField>) => void`	Callback when field metadata changes.

Error Handling

Prop	Type	Description
`onError`	`(err: Error) => void`	Callback for error handling.

Styling

Prop	Type	Description
`className`	`string`	CSS class applied to the root element.
`style`	`React.CSSProperties`	Inline styles applied to the root element.

Ref Handler (IGWHandler)

Access the handler via a React ref to control the component programmatically:

import { useRef } from 'react';
import { GraphicWalker } from '@kanaries/graphic-walker';
import type { IGWHandler } from '@kanaries/graphic-walker';
 
function App() {
  const gwRef = useRef<IGWHandler>(null);
 
  return <GraphicWalker ref={gwRef} data={data} fields={fields} />;
}

Handler Properties and Methods

Member	Type	Description
`chartCount`	`number`	Total number of chart tabs.
`chartIndex`	`number`	Currently selected chart tab index.
`openChart(index)`	`(index: number) => void`	Switch to a specific chart tab.
`renderStatus`	`'computing' \| 'rendering' \| 'idle' \| 'error'`	Current render status of the active chart.
`onRenderStatusChange(cb)`	`(cb: Function) => () => void`	Listen for render status changes. Returns a dispose function.
`exportChart(mode?)`	`(mode?: 'svg' \| 'data-url') => Promise<IChartExportResult>`	Export the current chart. Defaults to `'svg'`.
`exportChartList(mode?)`	`(mode?: 'svg' \| 'data-url') => AsyncGenerator`	Async generator that yields each chart's export data.

Export Example

async function handleExport() {
  if (!gwRef.current) return;
 
  // Export current chart as SVG
  const result = await gwRef.current.exportChart('svg');
  console.log(result.title, result.charts);
 
  // Export all charts
  for await (const item of gwRef.current.exportChartList('data-url')) {
    console.log(`Chart ${item.index + 1}/${item.total}:`, item.data.title);
  }
}

Examples

Basic Explorer

import { GraphicWalker } from '@kanaries/graphic-walker';
 
function Explorer({ data, fields }) {
  return <GraphicWalker data={data} fields={fields} />;
}

With Dark Mode and Theme

<GraphicWalker
  data={data}
  fields={fields}
  appearance="dark"
  vizThemeConfig="streamlit"
/>

With Toolbar Customization

<GraphicWalker
  data={data}
  fields={fields}
  toolbar={{
    exclude: ['export_chart'],
    extra: [
      {
        key: 'custom-save',
        label: 'Save',
        icon: SaveIcon,
        onClick: handleSave,
      },
    ],
  }}
/>

Server-Side Computation

import { GraphicWalker } from '@kanaries/graphic-walker';
import type { IComputationFunction } from '@kanaries/graphic-walker';
 
const computation: IComputationFunction = async (payload) => {
  const response = await fetch('/api/compute', {
    method: 'POST',
    body: JSON.stringify(payload),
    headers: { 'Content-Type': 'application/json' },
  });
  return response.json();
};
 
function App() {
  return (
    <GraphicWalker
      computation={computation}
      fields={fields}
    />
  );
}

Getting Started GraphicRenderer