Skip to content

Getting Started

This guide walks you through installing Graphic Walker and rendering your first interactive chart.

Prerequisites

  • Node.js 16+
  • React 17+ (React 18 recommended)

Installation

Install the package with your preferred package manager:

# npm
npm install @kanaries/graphic-walker
 
# yarn
yarn add @kanaries/graphic-walker
 
# pnpm
pnpm add @kanaries/graphic-walker

Basic Usage

Import the GraphicWalker component and pass it your data and field definitions:

import { GraphicWalker } from '@kanaries/graphic-walker';
 
const data = [
  { date: '2024-01-01', product: 'A', sales: 120, profit: 40 },
  { date: '2024-01-01', product: 'B', sales: 200, profit: 80 },
  { date: '2024-02-01', product: 'A', sales: 150, profit: 55 },
  { date: '2024-02-01', product: 'B', sales: 180, profit: 65 },
];
 
const fields = [
  { fid: 'date', name: 'Date', semanticType: 'temporal', analyticType: 'dimension' },
  { fid: 'product', name: 'Product', semanticType: 'nominal', analyticType: 'dimension' },
  { fid: 'sales', name: 'Sales', semanticType: 'quantitative', analyticType: 'measure' },
  { fid: 'profit', name: 'Profit', semanticType: 'quantitative', analyticType: 'measure' },
];
 
function App() {
  return <GraphicWalker data={data} fields={fields} />;
}
 
export default App;

That's it — this renders a full interactive visualization editor where users can drag fields to create charts.

Understanding Fields

Every field needs two type annotations:

Semantic Type

Tells Graphic Walker what kind of data this field contains:

Semantic TypeUse ForExamples
quantitativeContinuous numbersrevenue, temperature, count
nominalUnordered categoriesproduct name, country, color
ordinalOrdered categoriesrating (low/medium/high), education level
temporalDates and timesorder date, timestamp

Analytic Type

Tells Graphic Walker how to use the field in analysis:

Analytic TypeMeaningBehavior
dimensionGroup-by fieldUsed to split data into categories
measureAggregated fieldSummed, averaged, counted, etc.

Rule of thumb: If you'd GROUP BY it in SQL, it's a dimension. If you'd SUM() or AVG() it, it's a measure.

Loading Data from CSV

You can use any CSV parsing library. Here's an example with Papa Parse (opens in a new tab):

import { GraphicWalker } from '@kanaries/graphic-walker';
import Papa from 'papaparse';
import { useState, useEffect } from 'react';
 
function App() {
  const [data, setData] = useState([]);
  const [fields, setFields] = useState([]);
 
  useEffect(() => {
    Papa.parse('/data.csv', {
      download: true,
      header: true,
      dynamicTyping: true,
      complete(results) {
        setData(results.data);
        // Auto-generate field definitions from columns
        const cols = Object.keys(results.data[0] || {});
        setFields(
          cols.map(col => ({
            fid: col,
            name: col,
            semanticType: typeof results.data[0][col] === 'number' ? 'quantitative' : 'nominal',
            analyticType: typeof results.data[0][col] === 'number' ? 'measure' : 'dimension',
          }))
        );
      },
    });
  }, []);
 
  if (!data.length) return <div>Loading...</div>;
  return <GraphicWalker data={data} fields={fields} />;
}

Adding Pre-configured Charts

Pass the chart prop to show specific visualizations when the component loads:

import { GraphicWalker } from '@kanaries/graphic-walker';
import type { IChart } from '@kanaries/graphic-walker';
 
const charts: IChart[] = [
  {
    visId: 'chart-1',
    name: 'Sales by Product',
    encodings: {
      dimensions: [],
      measures: [],
      rows: [{ fid: 'sales', name: 'Sales', analyticType: 'measure', semanticType: 'quantitative' }],
      columns: [{ fid: 'product', name: 'Product', analyticType: 'dimension', semanticType: 'nominal' }],
      color: [],
      opacity: [],
      size: [],
      shape: [],
      theta: [],
      radius: [],
      longitude: [],
      latitude: [],
      geoId: [],
      details: [],
      filters: [],
      text: [],
    },
    config: {
      defaultAggregated: true,
      geoms: ['bar'],
      coordSystem: 'generic',
      limit: -1,
    },
    layout: {
      showTableSummary: false,
      stack: 'stack',
      showActions: false,
      interactiveScale: false,
      zeroScale: true,
      size: { mode: 'auto', width: 800, height: 600 },
      format: {},
      resolve: {},
    },
  },
];
 
function App() {
  return <GraphicWalker data={data} fields={fields} chart={charts} />;
}

Dark Mode

Control the appearance with the appearance prop:

// Follow system preference
<GraphicWalker data={data} fields={fields} appearance="media" />
 
// Always light
<GraphicWalker data={data} fields={fields} appearance="light" />
 
// Always dark
<GraphicWalker data={data} fields={fields} appearance="dark" />

Next Steps