ggaction

A grammar for how charts are made.

Most visualization grammars describe a finished chart. ggaction represents chart authoring itself as an immutable, traceable sequence of graphical actions.

Build, inspect, select, and revise charts one meaningful action at a time.

Start with a complete example, then use the API pages when you need to customize one part. The main, basic, extension, SVG, PNG, and PDF entry points include TypeScript declarations.

Experimental 0.0.12 · APIs may change before 1.0.0. Review the changelog when upgrading.

Start here

Build your first chart Install the package, render a complete chart, and understand the action chain. Start from a chart type Copy the shortest supported scatterplot, line, bar, or area flow. Find an action Look up exact signatures, defaults, inference, and related guides. Connect an LLM locally Use one read-only MCP search tool without preloading the full documentation.

Common chart types

Start with common Cartesian charts for relationships, comparisons, trends, and distributions.

Cars scatterplot of horsepower and fuel economy

Tutorial

Scatterplot

Compare two quantitative fields and encode a category with color.

createScatterPlot View full size

Aggregate cars line chart grouped by origin

Tutorial

Line chart

Aggregate values over time and split the result into series.

createLinePlot View full size

Heatmap of life expectancy by country and year with values inside colored cells

Recipe

Heatmap

Map two discrete fields to cells and a quantitative field to color.

createHeatmap createTextMark encodeText View full size

Grouped bar chart of job percentages

Tutorial

Bar chart

Aggregate ordinal categories and arrange nominal groups side by side.

createBarPlot View full size

Stacked histogram of car displacement

Tutorial

Histogram

Bin a quantitative field and count category partitions.

createHistogram View full size

Statistics and uncertainty

Compose ordinary marks and derived data into higher-level statistical views.

Cars scatterplot with grouped regression lines and confidence bands

Tutorial

Regression scatterplot

Layer observations, grouped fits, and confidence bands.

createPointMark createRegression View full size

Tukey box plot of fuel economy by origin

Recipe

Box plot

Compose quartiles, whiskers, medians, and outlier points.

createBoxPlot View full size

Alternative coordinates

Use parallel axes or angle and radial distance when Cartesian x and y are not the clearest structure for the comparison.

Cars of 1970 connected across fuel economy, horsepower, weight, and acceleration axes

Recipe

Parallel coordinates

Compare multivariate row profiles while retaining row-level identity.

createParallelCoordinates encodeParallelCoordinates View full size

Rose chart comparing three mortality causes across twelve months

Recipe

Rose chart

Compare radial magnitudes inside ordered categorical sectors.

createArcMark encodeTheta encodeR View full size

Browse the curated chart gallery →

Go deeper

Understand immutable ChartProgram state, semantic and graphical state, and action trace trees. Extension authors can continue with action authoring and the primitive API. For boundaries and failures, see supported features and troubleshooting. Language models can use the concise documentation index, the local read-only MCP server, or the generated full-text bundle.

Source, issues, and development history are available on GitHub.