Getting Started

Cars scatterplot of horsepower and fuel economy — Quantitative positions with nominal color.

This walkthrough installs ggaction, creates a complete scatterplot from an inline dataset, and renders it to Browser Canvas. Every action returns a new immutable ChartProgram, so the calls can be chained.

1. Create a browser project

ggaction is an ESM package. This minimal setup uses Vite to resolve the npm package for the browser:

mkdir ggaction-start
cd ggaction-start
npm init -y
npm install ggaction
npm install --save-dev vite

The command installs the public ggaction package from the npm registry.

Create index.html:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>ggaction scatterplot</title>
  </head>
  <body>
    <canvas id="chart" aria-label="Horsepower versus mileage"></canvas>
    <script type="module" src="/main.js"></script>
  </body>
</html>

2. Build the program

Create main.js:

import { chart, render } from "ggaction";

const cars = [
  { horsepower: 88, mpg: 27, origin: "USA" },
  { horsepower: 70, mpg: 36, origin: "Japan" },
  { horsepower: 110, mpg: 24, origin: "Europe" }
];

const program = chart()
  .createCanvas({
    width: 640,
    height: 400,
    margin: { top: 30, right: 30, bottom: 60, left: 70 }
  })
  .createData({ values: cars })
  .createScatterPlot({
    x: "horsepower",
    y: "mpg",
    color: "origin",
    guides: {
      axes: {
        x: { title: { text: "Horsepower" } },
        y: { title: { text: "Miles per gallon" } }
      }
    }
  });

const canvas = document.querySelector("#chart");
render(program, canvas.getContext("2d"));

createScatterPlot uses the current dataset, creates a point mark, assigns the x, y, and optional appearance encodings, and creates applicable guides. It records those regular actions as trace children rather than compiling a second chart specification. Pass data explicitly when a program contains more than one dataset candidate; pass id when a later multi-resource flow needs that mark identity.

The wrapped createGuides action infers the applicable axes and horizontal grid from the position encodings. The renderer reads only concrete graphicSpec values already produced by actions; it does not compile semanticSpec during rendering. A nominal point color encoding can produce a categorical legend; adding a matching shape encoding produces a composite color-and-shape legend.

3. Run it

npx vite

Open the local URL printed by Vite. The browser draws the chart into the Canvas created in index.html.

Package entries and compatibility

Import	Environment	Use
`ggaction`	Modern ESM browsers and Node.js 20+	Chart authoring and Browser Canvas rendering
`ggaction/extension`	Modern ESM browsers and Node.js 20+	Wrapped actions and public primitive authoring
`ggaction/png`	Node.js 20+ only	PNG file output through the native Canvas adapter

All entries include TypeScript declarations. The package does not publish CommonJS entry points. Import ggaction/png only from Node code; the default browser entry does not load filesystem or native PNG modules.

The release artifact is tested by installing its exact tarball into fresh JavaScript and TypeScript consumer projects. It is also tested in a browser and across the supported Node release matrix.

Runnable repository examples

The source repository also contains complete modules for the minimal getting-started chart, scatterplot, line chart, histogram, bar chart, heatmap, parallel coordinates, regression scatterplot, density area, violin plot, error bar, error band, box plot, mark selection, and program composition.

Copy a chart recipeStart from the shortest supported flow for a known chart type. Learn a complete workflowBuild a chart step by step and understand what each action adds. Find an exact actionLook up canonical signatures, defaults, inference, and errors.

Use Troubleshooting when inference or layout cannot make one safe choice. Render the same program to a file with PNG output.